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PREFACE 



This manual describes VS User Subroutines (USERSUBS), a collection of subroutines 
that provide programmers with system functions that are helpful in the development of 
application programs. 

Chapter 1 provides a brief statement of the functions performed by each subroutine. 
Chapter 2 contains information about the subroutines and their descriptions, defines 
terms used in the manual, and provides instructions for coding the programming state- 
ments needed to access and use the subroutines. Chapter 3 contains the subroutine 
descriptions. Each description lists the subroutine's function (s), the argument list 
required to access it, notes on its use, and at least one example. 

This manual is intended for a Wang VS user with programming experience. In particu- 
lar, the programmer should be familiar with at least one supported programming lan- 
guage and should know how to reference subroutines in that language (although brief 
instructions are included in the manual). The programmer should also be familiar with 
the reference manual for the programming language being used, the VS Programmer's 
Introduction, and the VS Program Development Tools. 

Use of some of these subroutines also requires an understanding of VS operating 
system details. The user should read, or be familiar with, the contents of both the VS 
Operating System Services and the VS Principles of Operation. 

The reader should direct any comments about the documentation to Wang via the 
Customer Comment form inside the back cover of the manual. 

The following VS manuals contain information useful to the programmer accessing 
USERSUBS: 



Programmer's Introduction 
Principles of Operation 
Operating System Services 
Program Development Tools 
Procedure Language Reference 
Programming language references: 
Assembly Language Reference 
BASIC Language Reference 
COBOL Language Reference 
FORTRAN Language Reference 
PL/I Language Reference 
RPG II Language Reference 



800-1 101 PI 
800-1 100P0 
800-1107OS 
800-1307PT 
800-1 205PR 

800-1200AS 
800-1 202BA 
800-1 201 CB 
800-1 208FR 
800-1 209PL 
800-1 203RP 
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CHAPTER 1 
SUBROUTINE FUNCTIONS 



This chapter provides a brief statement of the function (s) of each user subroutine. 
This information is included in the subroutine descriptions in Chapter 3, but is summa- 
rized here for your convenience. 

Subroutine Function 



BELL 
BITPACK 
BITUNPK 
CANCEL 

CEXIT 



CHKPARM 



COMPRESS 



DATE 



DAY 



Sounds the workstation alarm for a specified amount of time. 

Converts a binary string into its ASCII character equivalent. 

Converts an ASCII character string into its binary equivalent. 

Cancels execution of the calling program and displays a message on the 
workstation. The message consists of a message ID, a message issuer, 
and a message. 

Overrides system cancel processing. On abnormal program termination, 
you can press PF1 to enter debug processing, PF1 6 to cancel processing, 
or the HELP key to access the Modified Command Processor. CEXIT 
allows you to restrict debug processing, to associate PF1 6 with alternate 
processing, and to disable operation of the HELP key. 

Performs table checking on one or more GETPARM keyword fields 
entered by a user or a procedure in a previous GETPARM request. You 
can use it for any type of field checking, but it is primarily intended for 
GETPARM Limited Alphanumeric and Alphanumeric keyword field types. 

Converts a character string to compressed format. Compressed format 
can reduce storage for records with repeated characters. 

Performs the following date functions: (1 ) converts the current system 
date and time to a formatted string, (2) converts dates between 
Gregorian and Julian formats, (3) performs calculations with dates, and 
(4) determines the day of the week that corresponds to a given 20th cen- 
tury date. 

Computes the day of the week that corresponds to a specified 20th cen- 
tury date. 
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Subroutine Function 

DISMOUNT Initiates a dismount operation of a mounted disk or tape volume. 

EXPAND Converts a character string from compressed format to external format. 

EXPAND removes the special characters used to indicate repeated char- 
acters and produces text in noncompressed form. 

EXTRACT Provides information about the system and the program user. 

FIND Obtains one or more file, library, or volume names from complete or par- 

tial file, library, and volume names supplied by your program. Also indi- 
cates whether a specified file resides in a specified library and volume. 

FLOPIO Performs a variety of I/O operations on a nonlabeled (NL) diskette. 

GETPARM Enables you to generate parameter requests in a higher level language 
program. 

HEXPACK Converts a string of hexadecimal digits to its ASCII character equivalent. 

HEXUNPK Converts a string of ASCII characters into hexadecimal digits. 

LINK Allows your program to link to a program or procedure and to specify a 

cancel exit for the link. Your program can also specify any arguments 
that are needed to execute the linked program or procedure. 

LOADCODE Allows you to load specified microcode into a device. 

LOGOFF Terminates your program and logs you off the system. 

MESSAGE Allows communication of messages between workstations. 

MOUNT Allows you to mount a volume (disk or tape). 

PAUSE Causes a program to pause for a specified amount of time. 

PRINT Sends a print file to the print queue. 

PROTECT Changes the file security attributes of a file or library. 

PUTPARM Performs the following primary functions: (1 ) creates a parameter list 

(parameter reference block) to satisfy a subsequently generated parame- 
ter request, (2) retrieves a previously created parameter reference block, 
and (3) deletes existing parameter reference blocks. 
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Subroutine Function 

READFDR Provides information about a specified file, including control blocks or 
file characteristics. 

READVTOC Provides information from the Volume Table of Contents (VTOC). 

RENAME Allows you to rename a file or library, with the options of bypassing expi- 

ration date checking and limiting access rights for a program with special 
privileges. 

RETURN Allows your program to return through several levels of subroutine calls. 

SCRATCH Provides the ability to scratch a file or library, with the options of bypass- 
ing expiration date checking and limiting access rights for a program 
with special privileges. 

SEARCH Performs a binary search on a specified table for a particular element and 

indicates whether the element exists in the table. 

SET Sets any of the allowable defaults that are available through the Com- 

mand Processor SET Usage Constants function and the Procedure lan- 
guage SET command. 

SORT Sorts a character array on a specified field, in either ascending or 

descending order. Output from SORT can be either the sorted array or a 
locator-type array. (The elements in a locator-type array indicate the 
positions of the sorted elements in the character array.) 

STRING Provides the following string manipulation functions: (1 ) moves a string 

to another variable and pads it with a specified character, (2) moves a 
portion of a string to another variable, (3) centers a string, (4) left- or 
right-justifies a string, (5) reverses the order of characters in a string, 
and (6) translates the string according to a standard or user-specified 
translation table. 

SUBMIT Submits a background job to be run or held for later processing. 

UNITRES Allows you to reserve or release a device or peripheral processor on the 

system. 

UPDATFDR Allows you to update the VTOC entry of a file or library. 

WSXIO Performs I/O operations at the workstation and returns values associated 

with those operations. 
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CHAPTER 2 
INTRODUCTION 



2.1 PRELIMINARY INFORMATION 

2.1 .1 Why Use These Subroutines? 

These subroutines provide very useful functions to the application programmer. With- 
out them, it would frequently be necessary for you to know operating system details and 
how to program in Assembly language. These subroutines provide you with a simple 
means of accessing information that is not readily available. 

2.1 .2 Organization of Individual Subroutine Descriptions 

As much as possible, individual subroutine descriptions are similar in format. Each 
description is divided into four sections: FUNCTION, USAGE, NOTES, and EXAMPLE. A 
description of each section follows. 

FUNCTION Mentions briefly the functions performed by the subroutine. After reading 
this section, you should know whether the subroutine is suitable for an 
intended application. 

USAGE Provides a general form of the argument list and a detailed discussion of 

the use of each argument. The following information is included. 

Function: Some subroutines offer several different functions. When 
this is the case, a statement of each function appears before the applic- 
able list of arguments. 

Position: Indicates argument positions in the calling sequence. 

Argument: Includes a descriptive name for each argument. 

Type: Specifies the data type of the argument. Section 2. 1 .5 deals 
with data types. 

Size: Indicates the number of bytes the argument must have. 

Comments: Provides information about each argument, including its 
definition, restrictions on its use, and permissible values. 



NOTES Includes restrictions, precautions, programming hints, and other informa- 

tion about the subroutine. 
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EXAMPLES Illustrate the use of each subroutine. Most subroutines have examples 
written in COBOL; some in BASIC, RPG II, and FORTRAN. Examples 
were written and tested with the following compiler versions: 

BASIC 3.03.01 

COBOL 3.03.02 

FORTRAN 2.05.00 

RPG II 4.02.01 

2.1 .3 Conventions Used in the Manual 

Argument The USAGE section of each subroutine description begins with a general 
List argument list. Because subroutines have differing requirements, you can 

specify the argument list in a number of ways. 

"argl, ..., argn" means that there are n arguments, which you must 
specify in a particular order. The last argument in the general list indicates 
the maximum number of arguments that can be specified. 

"argn, arguments" means that, for a subroutine that performs several 
functions, a particular argument ("argn") selects a function, which has its 
own argument requirements. Each function is described in detail. 

"keyl, red, ..." means that the program specifies arguments in 
"keyword-receiver" pairs. A keyword selects a particular option, and a 
receiver is associated with, and must be specified for, that keyword. The 
receiver can have a value that must be sent to the subroutine, or it can 
contain a value provided by the subroutine. Section 2.1 .4 provides a defi- 
nition of keyword and receiver. 

Alpha n Indicates that the data type for the argument is alphanumeric and that 

the number of bytes it must contain is n. " Var" indicates that the program 
can select the number of bytes or that the number depends on the infor- 
mation returned by the subroutine. Section 2.1 .5 discusses alphanumeric 
data. 

Integer 4 Indicates that the data type of the argument is integer and that it must 

contain 4 bytes. This requirement presents a problem for COBOL pro- 
grammers and is discussed in Section 2.2.2. Section 2.1 .5 discusses 
integer data. 

2.1 .4 Terms Used in the Manual 

AID Indicates the workstation status (whether the keyboard is locked or 

Character unlocked) or which PF key the program operator pressed last. Table 

3-1 8 is a complete list of AID (Attention ID) characters with their hexa- 
decimal and ASCII character equivalents. 

Argument Values (or locations where values can be obtained) required by the sub- 

List routine. It also includes variable names (or locations) that contain values 

returned by the subroutine. The CALL statement that references the sub- 
routine typically contains an argument list. 
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CALL The statement that references the subroutine. It contains the CALL verb. 

Statement the subroutine name, and an argument list. Each supported programming 

language uses a different form of CALL statement. Each is discussed in 

Section 2.2. 

Character A sequence of alphanumeric characters, such as ABCDE or S#. These 
String subroutines limit most character strings to letters and numbers, although 

some use special characters. 

Keyword Selects an option provided by the subroutine. For example, the SET sub- 

routine allows you to set system parameters. For this subroutine, a key- 
word selects a parameter to be set. 

Receiver A variable that can be used to pass information to or receive information 

from a subroutine. 

Return Code Indicates whether or not the action requested by the program is success- 
ful. Many subroutines require that the program include an argument for a 
return code in the argument list. If the operation of the subroutine is suc- 
cessful, the value of the return code is zero. If unsuccessful, the return 
code corresponds to an error condition. For each subroutine that uses 
return codes, the subroutine description includes a table of codes and 
their meanings. 

X'nn' Hexadecimal representation for the value enclosed within quotes. 

2.1.5 Data Types 

All arguments contain data that is either alphanumeric or integer type. A discussion of 
both types follows. 

Alphanumeric Data 

Alphanumeric data consists of all characters in the character set, whether or not 
printable. Most alphanumeric subroutine arguments have values that are limited to 
uppercase letters and numbers, although some can use special characters and 
lowercase letters. 

Each character of alphanumeric data requires one byte of storage. The Size section of 
each argument description provides the required size of the argument. An Alpha argu- 
ment with size 8, for example, is an argument of eight alphanumeric characters requiring 
eight bytes of storage. 

The various programming languages treat alphanumeric data differently. Section 2.2 
explains each approach. 

Integer Data 

In these subroutines, all arguments having numeric values are integer type. Integers 
are whole numbers, expressed without fractional parts. 

All arguments in these subroutines that contain integer values require four bytes of 
storage. The subroutines do not require integer (fullword) alignment. 

Different programming languages have different ways of specifying and handling 
integer data. Section 2.2 discusses integer data. 
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2.2 HOW TO USE THE SUBROUTINES 

First, select the appropriate subroutine from the brief description in Chapter 1 and the 
detailed description in Chapter 3. 

Second, read the description of the subroutine and its arguments. Determine which 
values must be supplied by the program and which arguments contain values returned 
by the subroutine. 

Third, add the necessary statements to the program to define argument values, call 
the subroutine, and use the values returned in arguments. Each programming language 
treats these statements differently. The necessary statements are described in the sub- 
sections that follow. 

Fourth, run the program, first linking the external USERSUBS subroutine to it. Section 
2.2.6 contains brief instructions on the use of the LINKER; refer to the VS Program 
Development Tools for more detailed information. 

2.2.1 BASIC Language 

Calling the Subroutine 

The form of the BASIC language CALL statement for these subroutines is as follows: 
CALL "subname" ADDR (arguments) 

Subname is the name of the subroutine. The double quotation marks must be present in 
the CALL statement. 

Arguments must be enclosed within parentheses and must be separated by commas. 
They must appear in the order specified in the argument list. In addition, each argument 
must agree in type and size with the corresponding argument in the list. 

Alphanumeric Data 

Variables with alphanumeric values must have names whose last character is the 
dollar sign ($). Alphanumeric constants are specified by enclosing their values within 
single or double quotes. (Note that single-quote literals provide lowercase letters.) 

Example: 

0PT$ = "FC" 

PROTECTCLASS$ = "#" 

CALL "SET" ADDR (0PT$ , PROTECTCLASS$) 

are equivalent to 

CALL "SET" ADDR ( " FC " , "#") 

Use the DIM statement to specify the names and number of characters of all alpha- 
numeric variables. 

Example: 

DIM 0PT$2, PR0TECTCLASSS1 
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Integer Data 

A variable with an integer value is designated as integer data type by appending the 
"%" character to its name. An integer constant that is defined in the user program con- 
tains a number followed by the "%" character. An integer that is input to the program via 
the workstation or a data file, computed in the program, or converted from an alpha- 
numeric expression, is not followed by the "%" character. Integer data is stored in four 
bytes. 

Example: 

TIME% = 5% 

CALL "BELL" ADDR (TIME%) 

are equivalent to 
CALL "BELL" ADDR (5%) 

2.2.2 COBOL Language 

Arguments passed to a subroutine must be defined in the Data Division. They can be 
initialized in either the Data Division or the Procedure Division. 

Calling the Subroutine 

The form of the CALL statement in COBOL is as follows: 

CALL "subname" USING arguments 

Subname is the subroutine name; it must be enclosed within quotes. Arguments are 
passed by means of the USING phrase. If the argument list for the subroutine specifies a 
certain order for the arguments, they must appear in that order in the USING phrase. 
Arguments that provide data to the subroutine must be variables that have been 
assigned values. Literals cannot be passed as arguments. 

Alphanumeric Data 

To define a data item as alphanumeric, its PICTURE character-string must contain 
only the symbols A, X, and 9, but not all A's or all 9's. 

Alphanumeric data can be initialized in the Data Division with the VALUE clause. The 
value specified must be a nonnumeric literal (a character-string enclosed in double 
quotes) or a figurative constant. Alphanumeric data can be initialized in the Procedure 
Division with the ACCEPT, MOVE, READ...INTO, and DISPLAY AND READ statements. 

The following program segment uses the EXTRACT subroutine to illustrate initializa- 
tion of alphanumeric data by means of the VALUE clause and the ACCEPT and MOVE 
statements. 

Example: 

DATA DIVISION. 
WORKING-STORAGE SECTION. 
•THE NEXT LINE ILLUSTRATES INITIALIZATION BY THE VALUE CLAUSE. 
77 CURRENT-LIBRARY-KEYWORD X(2) VALUE "CL". 
77 CURRENT-LIBRARY-RECEIVER PIC X(8). 
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*THE NEXT ITEM IS INITIALIZED IN THE PROCEDURE DIVISION BY MOVE. 
77 CURRENT-VOLUME-KEYWORD PIC XX. 
77 CURRENT-VOLUME-RECEIVER PIC X(6). 
•THE NEXT ITEM IS INITIALIZED IN THE PROCEDURE DIVISION BY ACCEPT. 
77 KEYWORD-3 PIC XX. 
77 RECEIVER-3 PIC X(8) . 
PROCEDURE DIVISION. 
MAIN-PARAGRAPH. 

MOVE "CV" TO CURRENT-VOLUME-KEYWORD. 

ACCEPT KEYWORD-3. 

CALL "EXTRACT" USING CURRENT-LIBRARY-KEYWORD, 

CURRENT-LIBRARY-RECEIVER, CURRENT-VOLUME-KEYWORD , 
CURRENT-VOLUME-RECEIVER, KEYWORD-3, RECEIVER-3. 

Integer Data 

To define a data item as an integer, you must code the USAGE IS BINARY clause in the 
data description entry. 

COBOL integer items are stored in halfword (two-byte) binary format. The subrou- 
tines, however, accept only four-byte integer arguments. You can solve this problem by 
defining a four-byte group BINARY item composed of two elementary items. For 
example: 

01 GROUP-ITEM USAGE BINARY. 
03 FILLER VALUE ZERO. 
03 INTEGER-DATA. 

The CALL USING statement passes GROUP-ITEM to the subroutine. If you use GROUP- 
ITEM to send data to the subroutine, initialize FILLER to zero. The subroutine then 
receives the integer contained in INTEGER-DATA. If you use GROUP-ITEM to receive 
integer data from the subroutine, the calling program references the elementary item 
INTEGER-DATA rather than GROUP-ITEM on return from the subroutine. 

You must use other methods for negative integers and integers greater than 32767. 
These methods are explained below, after the discussion of initializing integer data. 

Use the VALUE clause to initialize integer data in the Data Division. The value that you 
specify must be a numeric literal (not enclosed in quotes) containing only digits or a fig- 
urative constant ZERO. 

There are several methods you can use to initialize integer items in the Procedure Divi- 
sion. The COMPUTE, MOVE, PERFORM...VARYING, and READ...INTO statements initial- 
ize integer items directly. You can use the ACCEPT statement to enter character repre- 
sentations of integers; integer data items can then be initialized by converting the char- 
acter representations to their numeric values. Perform the conversion by using the 
MOVE or MOVE WITH CONVERSION statement or a BASIC subroutine using the 
CONVERT statement, as explained later in this subsection. The DISPLAY AND READ 
statement can initialize integer items by transferring data entered at the workstation to 
an OBJECT field of the workstation screen description entry. 

In the program segment that follows, the READVTOC subroutine returns the names of 
the files in a library 1 files at a time, beginning with the first file in the library. This seg- 
ment illustrates initialization by means of the COMPUTE, MOVE, and 
PERFORM... VARYING statements, but is not meant to illustrate realistic programming 
practice. 
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WORKING-STORAGE SECTION. 
*THE NEXT ITEM IS INITIALIZED IN THE PROCEDURE DIVISION BY COMPUTE 
77 COMPUTABLE USAGE BINARY. 
77 TY-PE PIC X VALUE "F" . 
77 LIB-RARY PIC X(8). 
77 VOL-UME PIC X(6). 
01 STARTER. 
•TWO ELEMENTARY BINARY ITEMS FOLLOW. THE FIRST IS INITIALIZED 
'HERE BY THE VALUE CLAUSE. THE SECOND IS INITIALIZED IN THE 
•PROCEDURE DIVISION BY PERFORM DRYING. 
03 FILLER USAGE IS BINARY VALUE ZERO. 
03 STARTNUMBER USAGE IS BINARY. 
01 COUN-TER. 

03 FILLER USAGE IS BINARY VALUE ZERO. 
•THE NEXT ITEM IS INITIALIZED IN THE PROCEDURE DIVISION BY MOVE. 
03 COUNTNUMBER USAGE IS BINARY. 
77 RECEIVER PIC X(80). 
01 RETURNCODE. 

03 FILLER USAGE IS BINARY VALUE ZERO. 
03 RETURNVALUE USAGE IS BINARY. 
01 FILE-COUNT. 

03 FILLER USAGE IS BINARY. 
03 FILECOUNT USAGE IS BINARY. 
PROCEDURE DIVISION. 
MAIN- PARAGRAPH. 

ACCEPT LIB-RARY, VOL-UME. 
COMPUTE COMPUTABLE = 10 •• 1. 
MOVE COMPUTABLE TO COUNTNUMBER. 

PERFORM CALL-PARAGRAPH VARYING STARTNUMBER FROM 1 BY 10 
UNTIL COUNTNUMBER LESS THAN 10. 
CALL- PARAGRAPH. 

MOVE SPACES TO RECEIVER. 

CALL "READVTOC" USING TY-PE, LIB-RARY, VOL-UME, STARTER, 
COUN-TER, RECEIVER, RETURNCODE, FILE-COUNT. 

You can use negative integers or integers greater than 32767 by writing BASIC 
subroutines that use the CONVERT statement. For example, the EXTRACT user subrou- 
tine obtains the size of a program's Segment 2 area, which is always greater than 
32767. To get the Segment 2 size, the COBOL program must provide EXTRACT with a 
four-byte numeric receiver. Since the left-most bit of this field is used for the sign, the 
value received from EXTRACT cannot be interpreted as an integer. The BASIC 
CONVERT statement, however, can convert the four-byte item to a nine-byte item 
whose contents represent the sign and the integer value, although not in integer format. 
The following is an example of the COBOL code necessary to call a BASIC subroutine 
named 4T09, which converts data from four bytes to nine bytes. 

77 KEYWORD PIC X(2) VALUE "S2". 

01 TEMP PIC X(4). 

77 SEG-2-SIZE PIC S9(8). 

PROCEDURE DIVISION. 

MAIN-PARAGRAPH. 

CALL "EXTRACT" USING KEYWORD, TEMP. 

CALL "4T09" USING TEMP, SEG-2-SIZE. 
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The BASIC subroutine requires two parameters from the COBOL program: a four-byte 
item and an eight-byte signed item. The BASIC subroutine receives the contents of the 
four-byte item and converts it to a nine-byte item, with one byte for the sign and eight 
bytes for the value. The following is a BASIC subroutine that performs the conversion. 

10 SUB "4T09" ADDR (COBOL4 /., C0B0L9$) 

20 DIM C0B0L9$9 

40 CONVERT C0B0L4% TO C0B0L9$, P I C (+######## ) 

50 END 

You can use another BASIC subroutine to convert nine-byte alphanumeric data to 
four-byte integer data that can be negative or greater than 32767. The integer data can 
then be passed to a user subroutine. The subroutine follows. 

10 SUB "9T04" ADDR (C0B0L9$, C0B0L4%) 

20 DIM C0B0L9$9 

30 CONVERT C0B0L9$ TO C0B0L4% 

40 END 

You can employ a BASIC subroutine like 9T04 to invoke a user subroutine interac- 
tively supplying values for data items by means of the COBOL ACCEPT statement, 
which transfers only alphanumeric data. The BASIC subroutine converts alphanumeric 
data to the integer data required by the user subroutine. The following COBOL program 
segment demonstrates how to use the SET subroutine interactively to change the 
default lines per page for printer output. The keyword "LI" informs SET that the integer 
value passed is the number of lines per page. 

77 LINES-CODE PIC X(2) VALUE "LI" 
01 LINES-VALUE. 

03 SIGN-ITEM PIC X VALUE " + ". 
03 LINES-NUM PIC X(8) . 
01 LINES-PER PIC X(4) . 
PROCEDURE DIVISION. 
MAIN- PARAGRAPH. 

DISPLAY "TYPE IN LINES-NUM.". 

ACCEPT LINES-NUM. 

CALL "9T04" USING LINES-VALUE, LINES-PER 

CALL "SET" USING LINES-CODE, LINES-PER. 

STOP RUN. 

Integers from - 1 to -32768 can be passed without the use of a BASIC subroutine. 
First, define a group item composed of two BINARY items, as above. Second, the pro- 
gram moves HIGH- VALUES to the group item, then moves a negative numeric item to 
the low-order elementary item. In two's-complement notation, the HIGH-VALUES move 
has the effect of propagating the negative sign across the high-order half of the group 
item. For a positive number, the program moves LOW- VALUES. 

In the following program segment, the G+ function of the DATE subroutine adds a 
negative number to a given Gregorian date to determine the earlier date. 

77 FUNCTION PIC X(2) VALUE "G+". 

77 START-OATE PIC X(6) VALUE "810717". 

77 ADD-DAYS PIC S9(4) VALUE -0001. 
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01 INTEGER-DAYS. 

03 FILLER USAGE IS BINARY VALUE ZERO. 
03 HALFWORD-DAYS USAGE IS BINARY. 
77 END-DATE PIC X(6) . 
01 RETURN-KODE. 

03 FILLER USAGE BINARY VALUE ZERO. 
03 RETURNED USAGE BINARY. 
PROCEDURE DIVISION. 
MAIN-PARAGRAPH. 

MOVE HIGH-VALUES TO INTEGER-DAYS. 

MOVE ADD-DAYS TO HALFWORD-DAYS. 

CALL "DATE" USING FUNCTION, START-DATE, INTEGER-DAYS, 

END-DATE, RETURN-KODE. 
DISPLAY END-DATE. 

2.2.3 FORTRAN Language 

Calling the Subroutine 

The form of the FORTRAN language CALL statement is as follows: 
CALL subname (arguments) 

Subname is the name of the subroutine. Because subroutine names cannot exceed six 
characters, each subroutine whose name is longer has a note indicating the six-character 
name that must be used. 

Arguments are enclosed within parentheses and are separated by commas. The order 
in which the arguments appear must be the same as that specified in the argument list. 
Also, each argument must agree in type and size with the corresponding argument in 
the list. 

Alphanumeric Data 

Specify an alphanumeric constant by enclosing its value within single quotes. 
Example: 

OPT = 'FC 

PCLASS = '#' 

CALL SET (OPT, PCLASS) 

are equiualent to 
CALL SET CFC , '#') 

You can declare variables having alphanumeric values in specification statements 
(such as LOGICAL, INTEGER, or REAL). A variable having alphanumeric data can be any 
data type, although the number of characters it requires might determine which type is 
most appropriate. Table 2-1 provides examples of variable sizes and specification state- 
ments that define the space required by the variable ("name" indicates the variable 
name). 
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Table 2-1 . Alphanumeric Size and FORTRAN Specification Statements 



Number of 


Specification 


Characters 


Statement 


1 


LOGICAL* 1 name 


2 


INTEGEFT2 name 


3 


LOGICAL* 1 name (3) 


4 


INTEGER name or 




LOGICAL name 


6 


LOGICAL* 1 name(6) 


8 


REAL*8 name 


10 


LOGICAL* 1 named 0) 


16 


REAL*8 name(2) 


22 


LOGICAL*! name(22) 



Integer Data 

The program specifies integer data by indicating its value. 

Example: 

NSECS = 10 

CALL BELL (NSECS) 

are equivalent to 
CALL BELL (10) 

Designate a variable as integer data type by beginning its name with a letter between I 
and N, or by including its name in an INTEGER or IMPLICIT specification statement The 
following statements illustrate how to declare a variable (PRINTR) as integer type. 

Example: 

INTEGER PRINTR 

NFORM = 

PRINTR = 10 

CALL SET ('FN' , NFORM, 'PR' .PRINTR) 

Integer variables and constants are stored in four bytes by default. 
Use of Files with the Subroutines 

Some subroutines permit the use of files for output and require that the pointer to the 
file UFB be identified so that the necessary file information is present. FORTRAN does 
not provide the pointer to the UFB. To use a subroutine that requires a UFB address, you 
must code the call to the USERSUBS subroutine as either a BASIC or COBOL subroutine 
and link that subroutine to the program. The appropriate programming language refer- 
ence manual provides additional information. 
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2.2.4 PL/I Language 
Declaring the Subroutine 

A PL/I subroutine accesses the user subroutines as external procedures. PL/I programs 
must declare the names of these procedures with the ENTRY attribute. The ENTRY 
declaration must also indicate the data types of all arguments passed to or from the sub- 
routine. Because the user subroutines pass only alphanumeric and four-byte integer 
data, the ENTRY declaration should specify only CHARACTER and FIXED BINARY (3 1 ) 
data types. For example, a PL/I program that calls the SET subroutine must contain the 
following declaration: 

DECLARE SET ENTRY (CHARACTER ( 2) , CHARACTER ( 1) ) ; 

Calling the Subroutine 

The form of the PL/I CALL statement is as follows: 

CALL subname (arguments); 

Subname is the name of the subroutine. It must have been previously declared with the 
ENTRY attribute. Arguments must be enclosed within parentheses and separated by 
commas. The arguments must appear in the order specified in the argument list. To pre- 
vent undesirable data type conversion, each argument must agree in type and size with 
the corresponding argument in the list. 

Alphanumeric Data 

Variables with alphanumeric values should be declared with the CHARACTER data 
type and the length of the character string. Variables with the STATIC storage class can 
be assigned initial values in the declaration statement. Alphanumeric constants are speci- 
fied by enclosing their values within single or double quotes. 

Example: 

DECLARE OPT CHARACTERS) , PCLASS CHARACTER(l) ; 

OPT = 'FC ; 

PCLASS = '#' ; 

CALL SET (OPT, PCLASS); 

are equivalent to 

DECLARE OPT STATIC CHARACTERS) INITC'FC"); 
DECLARE PCLASS STATIC CHARACTER (1) INIT('#'); 
CALL SET (OPT, PCLASS); 

are equivalent to 
CALL SET CFC , "#") ; 

Integer Data 

Variables with integer values should be declared with the FIXED BINARY (3 1 ) data 
type. Variables with the STATIC storage class can be assigned initial values in the decla- 
ration statement. Integer constants are specified by indicating an integer value (i.e., 4). 
Because integer constants are assigned the FIXED DECIMAL data type by the PL/I 
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compiler, integer constants are automatically converted to the FIXED BINARY data type 
by the PL/I compiler when passed to the user subroutine. 

2.2.5 RPG II Language 

Calling the Subroutine 

To call USERSUBS subroutines, RPG II programs use the User Aid RPGCALL. 
RPGCALL creates an interface between the calling RPG II program and the USERSUBS 
subroutine so that arguments can be passed back and forth. To access RPGCALL, you 
must write a one-statement Assembly language program. This subsection explains how 
to code and use that program in calling USERSUBS subroutines. For additional informa- 
tion about calling subroutines in RPG II, refer to the VS RPG //Language Reference. 

In RPG II, the EXIT operation code indicates the point at which flow of control passes 
from a calling program to a subroutine. Factor 2 specifies the name of the subroutine 
that is to receive control; factor 1, the result field, and the resulting indicators must be 
left blank. 

Use the RLABL operation code to pass arguments from the calling program to the sub- 
routine. Each argument that is passed requires one RLABL statement; name the argu- 
ment in the result field. Factor 1 , factor 2, conditioning indicator (columns 9- 1 7), arid 
resulting indicator entries must be left blank. The RLABL statements for a subroutine call 
can appear anywhere in the calculations. The ULABL operation code is not used in calling 
USERSUBS subroutines. After execution of the subroutine, control returns to the first 
executable statement after the EXIT statement. 

You must take the following steps when using RPGCALL to call a USERSUBS 
subroutine: 

Step 1 . Be sure that RPGCALL is stored on the system. RPGCALL is available from 
the International Society of Wang Users (ISWU), Wang Laboratories, Inc., 
One Industrial Avenue, Lowell, MA 01 851, Tel. (617) 459-5000. 

Step 2. Write and assemble the short Assembler program described below. At 

assemble time, supply the name of the library on which the RPGCALL pro- 
gram resides. 

Step 3. Write and compile the calling program. In the EXIT statement, include the 

name of the assembled program file from Step 2 (instead of the name of the 
USERSUBS subroutine). The RLABL statements must list the arguments that 
are to be passed to the USERSUBS subroutine. (The arguments are passed to 
the Assembler program, which then passes them to the USERSUBS subrou- 
tine.) 

Step 4. Run the LINKER, either directly from the Command Processor or as an option 
when compiling the calling program from the EDITOR. You must link three 
program files: the calling program, the USERSUBS subroutine, and the 
assembled program file from Step 2. The result of the LINKER'S execution is 
one executable program file. 
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Format the short Assembler program as follows: 

12 3 4 5 6 7 

123456789012345678901234567890123456789012345678901234567890123456789012 

RPGCALL NAME=xxxxxx,CALL=yyYYYY. (arguments) C 

(arguments- continued) 

The word RPGCALL begins in column 1 of the first line. The remainder of the state- 
ment starts in column 20 with the word NAME. If all the arguments cannot fit on one 
line, a C in column 72 denotes a continuation. All continuation lines begin in column 1 6. 

The fields have the following meanings: 

xxxxxx — The name of the assembled version of the one-statement Assembler 

program. This name is included in factor 2 of the EXIT statement in the 
calling RPG II program. It cannot be longer than six characters and must 
be unique (not used for any other purpose in the program). 

yyvyyy _ The name of the USERSUBS subroutine that the program is calling. 

arguments — The list of arguments to be passed between the USERSUBS subroutine 
and the calling program. The arguments must be in the order and of the 
type expected by the subroutine. 

This Assembler statement tells the RPGCALL macro which subroutine is being called 
and which arguments are being passed. The calling program specifies the arguments in 
RLABL statements, as described earlier; the EXIT statement is used to transfer control to 
the one-statement Assembler program. When the EXIT statement is executed, 
RPGCALL calls the USERSUBS subroutine, resolving memory addresses, and sometimes 
converting data types. 

Each parameter in the list can be expressed in either of the following formats: 

FORMAT A: FIELD 

This format is used to pass an alphanumeric field. 

FORMATB: (FIELD, DIGITS, F) 

This format is used to pass an integer field. RPG II programs store 
all numeric fields internally in packed decimal format, while the 
USERSUBS subroutines require integer data in fullword binary 
format. RPGCALL performs the necessary conversions. 

Alphanumeric Data and Variables 

An alphanumeric field can have any valid RPG II field name: six characters (numerals 
and letters only), beginning with a letter. Field names cannot contain embedded blanks. 
A blank decimal position entry defines a field as alphanumeric. Alphanumeric literals can 
contain any ASCII characters and are always enclosed in quotes. 
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Integer Data and Variables 

An integer field can have any valid RPG II field name, as described above. A decimal 
position entry of defines a field as integer. Integer constants are not enclosed in 
quotes. 

Use of Files with the Subroutines 

Some subroutines permit the use of files for output and require that the pointer to the 
file UFB be identified so that the necessary file information is present. RPG II does not 
provide the pointer to the UFB. To use a subroutine that requires a UFB address, you 
must code the call to the USERSUBS subroutine as either a BASIC or COBOL subroutine 
and link that subroutine to the program. The appropriate programming language refer- 
ence manual provides additional information. 

2.2.6 How to Link Subroutines with Programs 

To use these subroutines, you must link the program with the USERSUBS subroutine. 
There are two ways to perform this link: 

1 . Through the EDITOR 

2. Through the LINKER 

Each method is described below. More detailed information on editing and linking 
appears rn the VS Program Development Tools. 

Linking through the EDITOR 

You can use the EDITOR to link a subroutine with a program that is being compiled. 
From the EDITOR special menu, PF9 (RUN) compiles and runs the program. Make the 
following changes to the Linker screen: LINK=YES causes linking to occur, and 
LIBRARY=USERSUBS searches that library for references to subroutines not contained 
in the program. Note that the library name should correspond to the library in which 
these subroutines reside on your system. 

If you are a FORTRAN programmer linking individual files by using the Linkfile screen 
instead of specifying the subroutine library name, you must add a step when accessing 
user subroutines whose usual names exceed six characters (e.g., GETPARM, EXTRACT). 
In this case, you must provide the name and location of both the shortened name (e.g., 
GETPRM, XTRACT) and the full name on the Linkfile screen. 

If you are programming in RPG II, you must also link the short Assembly language pro- 
gram that calls the RPGCALL macro. (Refer to Section 2.2.5.) 

Linking with the LINKER 

The LINKER combines a number of separately compiled program units to form a 
single executable program file. Use the LINKER to link your program with a USERSUBS 
subroutine when you have already compiled your program and saved the program file. 

Using the LINKER involves the following steps. First, invoke the LINKER by pressing 
PF1 (RUN) from the Command Processor. Enter LINKER as the program file. Then, on 



2-14 



the Options screen, specify the library that contains the USERSUBS subroutine to be 
linked with your program. Next, specify your program as an input file on an Input screen. 
(It is not necessary to specify more than one input file.) Finally, specify a file name for the 
program file output on the Output screen. This file contains the compiled program and 
subroutine. The result is an executable program that can be run directly from the Com- 
mand Processor. 

If you are a FORTRAN programmer linking individual files by using Input screens 
instead of specifying the subroutine library name, you must add a step when accessing 
user subroutines whose usual names exceed 6 characters (e.g., GETPARM, EXTRACT). 
In this case, you must specify the usual subroutine name and the shortened name on 
separate Input screens. For example, to access EXTRACT, you must link EXTRACT and 
XTRACT by specifying those names on separate Input screens. You may, of course, just 
specify the subroutine library on the Options or Library screen and not add this extra 
step. 

RPG II programmers must also link the short Assembly language program that calls 
the RPGCALL macro. (Refer to Section 2.2.5) 

When a subroutine is revised, making it necessary to replace its program file, the 
LINKER can make this replacement. Refer to the VS Program Development Tools for 
more information. Note that it may also be necessary to revise the calling sequence and 
recompile the program. 

How to Find the Subroutine Version Number 

You can obtain the version number of a USERSUBS subroutine by running the 
DISPLAY utility and displaying the subroutine's object code. The object code appears as 
a sequence of random characters. The subroutine version number appears near the 
beginning of the code. 
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CHAPTER 3 

SUBROUTINE DESCRIPTIONS 



BELL 

FUNCTION 

Sounds the workstation alarm for a user-specified amount of time. 



USAGE (argD 

Pos Argument Type Size 

arg! Time Integer 4 



Comments 

Amount of time to sound the workstation 

alarm, in tenths of a second. 

If zero or negative, the alarm is not sounded. 



NOTE 

The workstation must be closed before the program calls this subroutine (the calling 
statement cannot be immediately preceded by any statement that accesses the worksta- 
tion, either for input or for output). In BASIC, the CLOSE WS statement closes the 
workstation. 
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BELL Subroutine - A FORTRAN Example 



This program causes the workstation alarm to sound for 3/1 of a second. 

C SOUND THE WORKSTATION ALARM FOR 3/10 SECOND 

ITIME = 3 
C CALL BELL SUBROUTINE WITH 'ITIME' ARGUMENT 

CALL BELL (ITIME) 

END 
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BITPACK 

FUNCTION 

Converts a binary string into its ASCII character equivalent. 



USAGE (arg1,...,arg3) 
Pos Argument Type 



Size Comments 

var Binary string to convert, supplied by user 

program. Length must be a multiple of 8. 

var ASCII equivalent of the input string, returned 

by the subroutine. Must be at least 1 /8th the 
length of the input string. 

4 Length of the input string; must be a multiple 

of eight (any excess digits are ignored). 



NOTES 

1 . The subroutine does not check to ensure that the input string is binary. 

2. For FORTRAN programs, the name of this subroutine must be specified as 
BTPACK. 



argl 


Binary 
String 


Alpha 


arg2 


Receiver 


Alpha 


arg3 


Length 


Intege 
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BITPACK Subroutine - A FORTRAN Example 

This program requests that the user input a binary number from the workstation. The program then 
converts the number to its ASCII equivalent and displays it on the workstation. 

C 'RCVR' IS THE 1-CHARACTER ASCII EQUIVALENT TO THE BINARY STRING 

LOGICAL'l RCVR 
C 'STRING' IS AN 8-CHARACTER BINARY NUMBER 

REAL*8 STRING 

WRITE(0,101) ' ENTER 8 BINARY DIGITS:' 

READ(0,102) STRING 
C END PROGRAM IF STRING = 11111111 

IF(STRING .EQ. '11111111') GO TO 99 
C 
C CALL BITPACK SUBROUTINE CBTPACK' IN FORTRAN) 

CALL BTPACK(STRING,RCVR,8) 
C 

WRITE(0,103) RCVR 

101 FORMAT (A23) 

102 FORMAT (A8) 

103 FORMAT (IX, 'ASCII: ' ,A1) 
99 PAUSE 

END 
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BITUNPK 

FUNCTION 

Converts an ASCII character string into its binary equivalent. 



USAGE (arg1,...,arg3) 
Pos Argument Type 



argl ASCII 
String 

arg2 Receiver 



arg3 Length 



Size Comments 



Alpha var 
Alpha var 

Integer 4 



String of ASCII characters to be converted, 
supplied by the user program. 

Binary string, returned by the subroutine. 
The length of the receiver must be at least 8 
times the length of the input string. 

Length of the input string. 



NOTE 

For FORTRAN programs, the name of this subroutine must be specified as BTUNPK. 
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BITUNPK Subroutine - A FORTRAN Example 

This example requests that the user input an ASCII string from the workstation. The program then 
converts the string to its binary equivalent and displays it on the workstation. 

C 'OUT' CAN HOLD UP TO 24 SEPARATE CHARACTERS 

REAL*8 0UT(3) 

WRITE(0,101) 

READ(0,102) IN 
C USER ENTERS 'QQQ' TO STOP 

IFUN .EQ. 3HQQQ) GO TO 99 
C 
C CALL BITUNPK ('BTUNPK' IN FORTRAN) 

CALL BTUNPK (IN, OUT, 3) 
C 

WRITE(0,103) OUT 

101 FORMATC ENTER 1-3 CHARACTERS (QQQ TO STOP)') 

102 FORMAT (A3) 

103 FORMATC BINARY: ' ,3A8) 
99 PAUSE 

END 
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CANCEL 



FUNCTION 

Cancels execution of the calling program and displays a message on the workstation. 
The message consists of a message ID, a message issuer, and a message that can be 
several lines in length. 



USAGE (argl arg5) 

Pos Argument Type Size 

arg 1 Msg ID Alpha 4 



arg2 Message 
Issuer 

arg 3 Msg Text 
Line Count 



Alpha 6 
Integer 4 



arg4 Message 
Text 



Alpha 



var 



arg 5 Msg Text 
Length 



Integer 



Comments 

Message identification, supplied by the user 
program. 

Message issuer identifier, supplied by the 
user program. 

Number of message text lines. The program 

can specify the message as separate text 

lines (include arg3), or as a block containing 

the complete text (omit arg3). 

If arg3 is specified, arg4 and arg5 are 

repeated for each text line. 

If arg3 is omitted, see arg4 for action. 

Message to be displayed. 
Arg3 specified: arg4 is a single line of text, 
containing no embedded X'OD' characters. 
Each line can begin with the following con- 
trol characters, singly or in combination: 
X'5E' (up-arrow) — center msg text 
X'5F' (underscore) — underline msg text 
X'2V (exclamation pt) — blink msg text 
Arg3 omitted: the message can consist of 
several lines of text, where lines are 
separated by a single X'OD' character. No 
control characters are recognized. 

Length of message text. 
Include control characters in text length. A 
text length of zero (excluding control charac- 
ters) generates no text line. If the argument 
list consists only of empty text strings, the 
subroutine generates a single blank as the 
message. 

Arg3 specified: length of text line (arg4). 
Arg3 omitted: length of entire msg (arg4). 



NOTE 

CANCEL terminates the program, displays a message on the workstation, and allows the 
user to enter debug processing or cancel processing. 
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CANCEL Subroutine — A BASIC Example 

This program terminates execution and displays a message on the screen. The user supplies the 
message ID, issuer, and the cancel message. 

000100DIM MESSAGEID$4 , ISSUER$6 ,MESSAGE$60 

000200ACCEPT 

000300 AT (01,25), 

000400 "DEMONSTRATION OF CANCEL SUBROUTINE", 

000500 AT (08,03), 

000600"Message ID:", 

000700 AT (08,20), MESSA6EID$ , CH(04), 

000800 AT (09,03), 

000900"Issuer:" , 

001000 AT (09,20), ISSUERS , CH(06), 

001100 AT (10,03), 

001200"Cancel Message:", 

001300 AT (10,20), MESSAGES , CH(60), 

001400 AT (14,03), 

001500"Fill in the information and press ENTER. The program will cance 

0016001 with the", 

001700 AT (15,03), 

001800"above information." 

001900 CALL "CANCEL" ADDR(MESSAGEID$, ISSUERS .MESSAGES, 60%) 
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CEXIT 



FUNCTION 

Overrides system cancel processing. 

On abnormal program termination, the user can press PF1 to enter debug processing, 
PF1 6 to cancel processing, or the HELP key to access the Modified Command Processor. 
CEXIT allows the programmer to restrict debug processing, to associate PF1 6 with alter- 
nate processing, and to disable operation of the HELP key. 



USAGE (arg1,...,arg5) 
Pos Argument Type 

arg 1 Type Alpha 



arg2 Cancel Alpha 

Option 



Size 

1 



arg3 HELP Key Alpha 
Option 



arg4 



arg 5 



PF16 
Message 



PF16Msg 
Length 



Alpha 



var 



Integer 4 



Comments 

Indicates whether to set or cancel options: 
S = Set options. 

C = Cancel options (no further arguments 
are required). 

Indicates whether to allow debug processing 
after abnormal program termination: 

Blank = Normal cancel processing 
(default). 

N = No debug processing. 

D = No debug processing. Provide dump. 
Optional. It might not be desirable to initiate 
debug processing after abnormal program 
termination when the user is not the program 
developer. 

Action of HELP key: 

H = Enable HELP key (default). 

N = Disable HELP key. 
Disabling the HELP key might be desirable 
when the program operator should not have 
access to the Command Processor. 

Allows replacement of the PF1 6 message 
for cancel option after abnormal termination. 
Default is no message replacement. 
If included, arg 5 must be included. 

Length of PF1 6 message. Maximum of 27 
characters. Must be included if arg4 is pre- 
sent. 



NOTE 

Arguments 2 through 5 are optional. However, if any are included, all preceding argu- 
ments must be included. 
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CEXIT Subroutine — A COBOL Example 



This program sets the Nodebug option and disables the HELP key for a cancel exit. 



000100 IDENTIFICATION DIVISION. 

000200 PROGRAM-ID. CEXITC. 

000300 ENVIRONMENT DIVISION. 

000400 DATA DIVISION. 

000500 WORKING-STORAGE SECTION. 

000600*THE FOLLOWING ARE THE FIRST THREE ITEMS FROM THE CEXIT ARGUMENT 

000700'LIST. 

000800 77 CEXIT-TYPE PIC X VALUE "S" . 

000900 77 C-OPTION PIC X VALUE "N" . 

001000 77 HELP-OPTION PIC X VALUE "N". 

001100 PROCEDURE DIVISION. 

001200 MAIN-PARAGRAPH. 

001300 CALL "CEXIT" USING CEXIT-TYPE, 

001400 # THE NEXT INSTRUCTION ALLOWS THE USER 

001500'DISABLED HELP KEY OPTION BY PRESSING 

001600'SCREEN IS DISPLAYED. 

001700 DISPLAY "THE HELP KEY IS DISABLED. 

001800 STOP RUN. 



C-OPTION, HELP-OPTION. 

TO TEST THE RESULTS OF THE 

THE HELP KEY WHILE THE 
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CHKPARM 



FUNCTION 

Performs table checking on one or more data fields entered previously by a user or 
procedure. It can be used for any type of field checking but is primarily intended for 
GETPARM Limited Alphanumeric and Alphanumeric keyword field types (refer to the 
GETPARM subroutine). CHKPARM can optionally identify abbreviations of various 
lengths for the table entries it is checking. 



USAGE (argl , ..., arg6) for each keyword to be checked 

The CHKPARM subroutine argument list consists of one or more sets of arguments, 
each consisting of six arguments. There is one set for each GETPARM keyword field 
that the subroutine checks. 



Pos Argument Type Size 

argl Field Alpha var 



arg2 Length 

arg3 Table 
Size 



arg4 String 
Table 



Integer 4 



Integer 4 



Alpha 



var 



arg5 Length See Note 1 

Table/Flag 

arg6 Ret. Code Integer 4 



Comments 

Name of data field whose value is to be 
checked. 

Field length. It must be positive and cannot 
exceed 256. 

Number of comparison strings in the table 
that follows, against which the subroutine 
checks data values. It must be positive. 

Character string array, which is the table of 
comparison strings. The length of each table 
element must be that of the keyword field 
itself, as specified in arg2. The table check 
proceeds in element order, starting from the 
first element, until either a match is found or 
the table is exhausted. 

See Note 1 for information. 



Return code, set to the table element 
number that matches the keyword field. If 
the subroutine does not find a match, the 
return code is set to zero. 
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NOTES 



The program can use argument 5 to indicate legal abbreviations for the acceptable 
field values (e.g., "Y" or "YE" allowed for "YES"); these abbreviations can be 
either a letter (N or A) or an integer table. If no such abbreviations are to be 
allowed, then the program specifies N for this argument. Conversely, if all possible 
abbreviations (which must be at least one character) are to be allowed, the pro- 
gram specifies A (for all abbreviations). 

For special cases in which some, but not all, abbreviations are to be allowed, 
neither N nor A is adequate. This argument becomes, instead, a table of "minimum 
lengths." This table is in the form of an integer array having exactly as many ele- 
ments as the compare string table (arg4), with each integer element corresponding 
to the comparably placed string element. The integer value is the minimum 
number of compare string characters that must be present in the keyword field in 
order to recognize a match. For example, a compare string of "INDEX" and a mini- 
mum length of 3 matches keyword fields "IND ", "INDE ", and "INDEX", but will 
not match "IN ", since it has fewer than 3 of the compare string characters. A 
minimum length of matches any abbreviation of the compare string, and also 
matches a completely blank field (used for "default" values); a minimum length 
that is equal to the field length (arg2) has the same effect as "no abbreviation"; a 
minimum length greater than the field length specifies "never match." Finally, a 
minimum length table containing all 1 values has the same effect as specifying 
argument value A, rather than passing the entire table (see above). 

For FORTRAN programs, the name of this subroutine must be specified as 
CHKPRM. 
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CHKPARM Subroutine — A COBOL Example 



This program calls the GETPARM subroutine to solicit parameters for an output file. It then calls the 
CHKPARM subroutine to check which of four possible values was entered in response to the 
GETPARM request for the file's device type. The program instructs CHKPARM to accept abbrevia- 
tions for the device types. Each device type has a different length abbreviation. 



000100 

000200 

000300 

000400 

000500 

000600 

000700 

000800 

000900 

001000* 

001100 

001200 

001300 

001400 

001500 

001600 

001700* 

001800* 

001900* 

002000* 

002100* 

002200 

002300 

002400 

002500 

002600 

002700 

002800 

002900 

003000 

003100 

003200 

003300 

003400 

003500 

003600 

003700 

003800 

003900 

004000 

004100 

004200 

004300 



IDENTIFICATION DIVISION. 
PROGRAM-ID. CHKPARMC. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
FIGURATIVE-CONSTANTS. 

CENTER IS "5E". 

BLINK IS "21" . 
DATA DIVISION. 
WORKING-STORAGE SECTION. 

THE FOLLOWING ITEMS ARE PARAMETERS FOR THE GETPARM SUBROUTINE 
77 TY-PE PIC X(2) VALUE "I". 
77 F0-RM PIC X VALUE "R". 
77 PR-NAME PIC X(8) VALUE "OUTPUT". 
77 KEY-RECEIVER PIC X(l) . 

77 MESSAGE-NUMBER PICXU) VALUE "9999". 
77 MESS-ENGER PIC X(7) VALUE "CHKPARM". 

AS EXPLAINED IN SECTION 2.2.2, COBOL ACCEPTS HALFWORD INTEGERS 
ONLY. DEFINE A FOUR-BYTE GROUP ITEM TO BE COMPOSED OF TWO 
HALFWORD-BINARY ELEMENTARY ITEMS, AND USE THE LOW-ORDER TWO 
BYTES FOR THE INTEGER. TO PASS AN INTEGER TO THE SUBROUTINE, 
INITIALIZE THE HIGH-ORDER BYTES TO ZERO. 
01 LINE-COUNT. 

03 FILLER USAGE IS BINARY VALUE 0. 

03 LINE-OFFSET USAGE IS BINARY VALUE 1. 

MESS-AGE. 

03 C0NTR0L-1 PIC X VALUE CENTER. 

03 CONTROL-2 PIC X VALUE BLINK. 

03 TEXT PIC X(27) VALUE "PLEASE SUPPLY THESE VALUES". 

MESSAGE-LENGTH. 

03 FILLER USAGE IS BINARY VALUE 0. 

03 M-LENGTH USAGE IS BINARY VALUE 29. 

KEYWORD-TYPE PIC X VALUE "K". 

KEYWORD-1 PIC X(8) VALUE "FILE". 

VALUE-1 PIC X(8) VALUE SPACES. 

VALUE-LENGTH. 

03 FILLER USAGE BINARY VALUE 0. 

03 LENGTH USAGE BINARY VALUE 8. 

ROW-1. 

03 FILLER USAGE IS BINARY VALUE 0. 

03 ROW-VALUE-1 USAGE IS BINARY VALUE 1. 

C0LUMN-1. 

03 FILLER USAGE IS BINARY VALUE 0. 

03 C0LUMN-VALUE-1 USAGE IS BINARY VALUE 10. 



01 



01 



77 
77 
77 
01 



01 



01 
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004400 77 

004500 77 

004600 77 

004700 01 

044800 

004900 

005000 77 

005100 77 

005200 01 

005300 

005400 

005500 01 

005600 

005700 

005800 77 

005900*THE 

006000 77 

006100*THE 

006200 01 

006300 

006400 

006500 01 

006600 

006700 

006800 # THE 

006900 01 

007000 

007100 

007200 

007300 

007400 01 

007500 

007600 01 

007700 

007800 

007900 01 

008000 

008100 

008200 

008300 

008400 

008500 

008600 

008700 

008800 

008900 

009000 

009100 

009200 01 

009300 

009400 

009500 



DATA-TYPE PIC X(2) UUUE "L". 

KEYW0RD-2 PIC X(8) UUUE "LIBRARY". 

UUUE-2 PIC X(8) UUUE SPACES. 

ROW- 2. 

03 FILLER USAGE IS BINARY UUUE. 0. 

03 ROW-UUUE-2 USAGE IS BINARY UUUE 4. 

KEYWORD-3 PIC X(6) UUUE "VOLUME". 

VALUE-3 PIC X(6) UUUE SPACES. 

UUUE-3-LENGTH. 

03 FILLER USAGE IS BINARY UUUE 0. 

03 VOLUME-LENGTH USAGE IS BINARY UUUE 6. 

ROW-3. 

03 FILLER USAGE IS BINARY VALUE 0. 

03 ROW-UUUE-3 USAGE IS BINARY UUUE 4. 

KEYWORD-4 PIC X(6) UUUE "DEVICE". 

FOLLOWING IS THE GETPARM ITEM THAT WILL BE CHECKED BY CHKPARM 

UUUE-4 PIC X(7) UUUE SPACES. 

NEXT ITEM IS PASSED BOTH TO GETPARM AND CHKPARM. 

VALUE-4-LENGTH. 

03 FILLER USAGE IS BINARY UUUE 0. 

03 DEVICE-LENGTH USAGE IS BINARY UUUE 7. 

ROW-4. 

03 FILLER USAGE IS BINARY VALUE 0. 

03 ROW-VALUE-4 USAGE IS BINARY UUUE 4. 

NEXT ITEM CONTAINS THE UUUES TO BE CHECKED BY CHKPARM 

DEVICES. 

03 FILLER 

03 FILLER 

03 FILLER 

03 FILLER 



PIC 
PIC 
PIC 
PIC 



UUUE 
UUUE 
UUUE 
UUUE 



DISK". 
DISPLAY' 
PRINTER' 
TAPE ' ' . 



X(7) 
X(7) 
X(7) 
X(7) 

DEVICE-TABLE REDEFINES DEVICES. 
03 DEVICE PIC X(7) OCCURS 4 TIMES. 
DEVICE-TABLE-SIZE. 
03 FILLER USAGE IS BINARY UUUE 0. 
03 DEVICE-TABLE-LENGTH USAGE BINARY VALUE 4. 
LENGTHS. 
03 INTEGER-1. 

05 FILLER USAGE BINARY UUUE 0. 

05 LENGTH-1 USAGE BINARY UUUE 3. 
03 INTEGER-2. 

05 FILLER USAGE BINARY UUUE 0. 

05 LENGTH-2 USAGE BINARY UUUE 4. 
03 INTEGER-3. 

05 FILLER USAGE BINARY UUUE 0. 

05 LENGTH-3 USAGE BINARY UUUE 5. 
03 INTEGER-4. 

05 FILLER USAGE BINARY UUUE 0. 

05 LENGTH-4 USAGE BINARY UUUE 2. 
LENGTH-TABLE REDEFINES LENGTHS. 
03 LENGTH-INTEGER OCCURS 4 TIMES. 

05 FILLER USAGE BINARY. 

05 LENGTH-VALUE USAGE BINARY. 
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009600 01 RETURN-KODE. 

009700 03 FILLER USAGE BINARY VALUE ZERO. 

009800 03 TABLE-ITEM USAGE BINARY. 

009900 PROCEDURE DIVISION. 

010000 MAIN-PARAGRAPH. 

010100 CALL "GETPARM" USING TY-PE, FO-RM, PR-NAME, KEY-RECEIVER, 

010200 MESSAGE-NUMBER, MESS-ENGER, LINE-COUNT, MESS-AGE, 

010300 MESSAGE-LENGTH, KEYWORD-TYPE, KEYWORD-1, VALUE-1, 

010400 VALUE-LENGTH, ROW-1, COLUMN-1, DATA-TYPE, 

010500 KEYWORD-TYPE, KEYWORD-2, VALUE-2, VALUE-LENGTH, ROW-2, 

010600 COLUMN-1, DATA-TYPE, KEYWORD-TYPE, 

010700 KEYWORD-3, VALUE-3, VALUE-3-LENGTH, ROW-3, 

010800 COLUMN-1, DATA-TYPE, 

010900 KEYWORD-TYPE, KEYWORD-4, VALUE-4, VALUE-4-LENGTH , 

011000 ROW-3, COLUMN-1, DATA-TYPE. 

011100 IF VALUE-1 = "Z" STOP RUN. 

011200 CALL "CHKPARM" USING VALUE-4, VALUE-4-LENGTH , 

011300 DEVICE-TABLE-SIZE, DEVICE-TABLE, LENGTH-TABLE, 

011400 RETURN-KODE. 

011500 DISPLAY TABLE-ITEM. 

011600 GO TO MAIN-PARAGRAPH. 
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COMPRESS 



FUNCTION 

Converts a character string to compressed format. Compressed format can reduce stor- 
age for records with repeated characters. 



USAGE (arg1,...,arg5) 
Pos Argument Type 

arg! Input Alpha 



arg2 

arg3 
arg4 



Input 
length 

Output 

Output 
Length 



Size Comments 



Integer 

Alpha 
Integer 



var 
4 

var 
4 



arg 5 Ret. Code Integer 4 



Character string to be compressed. 

Length of input string. Must be nonnegative 
and not greater than 2048. 

Receiver for compressed string. 

Maximum length of output receiver. Must be 
between and 2048 and is reduced by the 
subroutine to reflect the actual size of the 
compressed string. 

Error return code: 
=Successful. 
4 =Maximum output length (arg4) too 

short, contents of the output string 

are unpredictable. 



NOTES 

1 . The operation of this subroutine is identical to the process used by the COMP 
Assembler instruction, which is used by DMS to generate compressed records. 

2. For FORTRAN programs, the name of this subroutine must be specified as 
CMPRES. 

3. This subroutine does the reverse of the EXPAND subroutine. 
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COMPRESS And EXPAND Subroutines — A COBOL Example 



This program calls COMPRESS to compress a character string and displays the compressed string in 
ASCII characters. It calls HEXUNPK to display the compressed string in hexadecimal characters, calls 
EXPAND to expand the string, and displays the expanded string. 



000100 

000200 

000300 

000400 

000500 

000600 

000700 

000800 

000900 

001000 

001100 

001200 

001300 

001400 

001500 

001600 

001700 

001800 

001900 

002000 

002100 

002200 

002300 

002400 

002500 

002600 

002700 

002800 

002900 

003000 

003100 

003200 

003300 

003400 

003500 

003600 

003700 

003800 

003900 

004000 



IDENTIFICATION DIVISION. 
PROGRAM-ID. COMPRESC. 
ENVIRONMENT DIVISION. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 

77 INPUT-STRING PICX(21) VALUE "ABBCCCDDDDEEEEEFFFFFF" . 
*AS EXPLAINED IN SECTION 2.2.2, COBOL ACCEPTS HALFWORD INTEGERS 
•ONLY. DEFINE A FOUR-BYTE GROUP ITEM TO BE COMPOSED OF TWO 
•HALFWORD-BINARY, ELEMENTARY ITEMS, AND USE THE LOW-ORDER TWO 
•BYTES FOR THE INTEGER. TO PASS AN INTEGER TO THE SUBROUTINE 
•INITIALIZE THE HIGH-ORDER BYTES TO ZERO. 
01 INPUT-LENGTH. 

03 FILLER USAGE IS BINARY VALUE 0. 
03 IN-LENGTH USAGE IS BINARY VALUE 21. 
OUTPUT-STRING PIC X(12) . 
OUTPUT-LENGTH. 

03 FILLER USAGE IS BINARY VALUE 0. 
03 OUT-LENGTH USAGE IS BINARY VALUE 12. 
HEX-STRING PIC X(24) . 
EXPANDED-STRING PIC X(21) . 
RETURNCODE. 
03 FILLER USAGE IS BINARY VALUE ZERO. 
03 ERROR-CODE USAGE IS BINARY VALUE 0. 
PROCEDURE DIVISION. 
MAIN-PARAGRAPH. 

CALL "COMPRESS" USING INPUT-STRING, INPUT-LENGTH, 

OUTPUT-STRING, OUTPUT-LENGTH, RETURNCODE. 

IF ERROR-CODE NOT = 0, DISPLAY "OUTPUT LENGTH TOO SHORT" 

GO TO EXIT- PARAGRAPH. 
DISPLAY OUTPUT-STRING. 
CALL "HEXUNPK" USING OUTPUT-STRING, HEX-STRING, 

OUTPUT-LENGTH. 
DISPLAY HEX-STRING. 
CALL "EXPAND" USING OUTPUT-STRING, OUTPUT-LENGTH, 

EXPANDED-STRING, INPUT-LENGTH, RETURNCODE. 
IF ERROR-CODE NOT = 0, DISPLAY "ERROR CODE = "ERROR-CODE, 

GO TO EXIT- PARAGRAPH. 
DISPLAY EXPANDED-STRING. 
EXIT-PARAGRAPH. 

STOP RUN. 



77 
01 



77 
77 
01 
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DATE 



FUNCTION 

DATE has several functions that involve the current system date, as well as user- 
specified dates: 

1 . Converts current system date and time to a formatted string, suitable for 
report headings, in uppercase or upper and lowercase. 

2. Converts dates between Gregorian and Julian formats (see definitions in 
USAGE section). 

3 Performs calculations with dates, including finding the difference between 
two dates and obtaining a new date by adding a number of days to a given 
date. 

4. Determines the day of the week corresponding to a given date in the 20th 
century. 



USAGE (arg 1 , arguments) 

Arg 1 defines the function and determines the number and nature of the additional 
arguments. 

Several of this subroutine's functions use Gregorian and Julian formats For ^example, . 
for the calendar day January 20, 1 981 , the Gregorian equivalent (in YYMMDD format) .s 
8101 20; the Julian equivalent (in YYDDD format, where DDD is the number of days 
from January 1) is 8 1020. 

1 . Get current date and time (uppercase) 

Pos Argument Type Size Comments 



argl 
arg2 



Function 
Date/Time 



Alpha 
Alpha 



2 Value is HD 

45 Returned by the subroutine, in the following 

format: 



AAAAAAAAA 
FRIDAY 



BBBBBBBBBBBBBBBBBB CCCCCCCC 

JANUARY 20, 1979 2:30 PM 



2. Get current date and time (upper and lowercase) 
Pos Argument Type Size Comments 

arg 1 Function Alpha 



arg2 



Function 
Date/Time 



Alpha 



2 
45 



Value is HL 

Returned by the subroutine, in the following 

format: 

AAAAAAAAA BBBBBBBBBBBBBBBBBB 
Friday January 20, 1979 



CCCCCCCC 
2:30 PM 
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3. Convert date in Gregorian format to Julian format 

Pos Argument Type Size Comments 

argl Function Alpha 2 Value is G J 

arg2 Greg. Date Alpha 6 Supplied by user program. 

arg3 Jul. Date Alpha 5 Returned by subroutine. 

arg4 Ret. Code Integer 4 Error return code. See Table 3- 1 below. 



4. Convert date in Julian format to Gregorian format 
POs Argument Type Size Comments 

2 



argl 
arg2 
arg3 
arg4 

5. 

Pos 

argl 
arg2 
arg3 
arg4 

arg5 

6. 

Pos 

argl 
arg2 
arg3 
arg4 



Function Alpha 2 Value is JG 

Jul. Date Alpha 5 Supplied by user program. 

Greg. Date Alpha 6 Returned by subroutine. 

Ret. Code Integer 4 Error return code. See Table 3-1 below. 

Compute the difference between two dates in Gregorian format 



Argument 

Function 

Start Date 

End Date 

Difference 
in Days 

Ret. Code 



Type 

Alpha 
Alpha 
Alpha 
Integer 



Size Comments 



2 

6 
6 
4 



Integer 4 



Value is G- 

Supplied by user program. 

Supplied by user program. 

Returned by subroutine. This value can be 
positive or negative. 

Error return code. See Table 3-1 below. 



Compute the difference between two dates in Julian format 
Argument Type Size Comments 



Function 

Start Date 

End Date 

Difference 
in Days 



Alpha 
Alpha 
Alpha 
Integer 



2 
5 
5 

4 



arg5 Ret. Code Integer 4 



Value is J- 

Supplied by user program. 

Supplied by user program. 

Returned by subroutine. This value can be 
positive or negative. 

Error return code. See Table 3-1 below. 
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7. 

Pos 

argl 
arg2 
arg3 



Add a specified number of days to a Gregorian date to produce a new date 
Argument Type Size Comments 



Function 

Start Date 

Days to 
Add 



Alpha 
Alpha 
Integer 



2 

6 
4 



arg4 New Date Alpha 



arg5 Ret. Code Integer 4 



Value is G+ 

Supplied by user program. 

Supplied by user program. Must be in the 
range of -36524 to +36525. If outside that 
range, a return code of 8 results. 

Returned by subroutine. If the new date is in 
the 1 9th or 21 st century, a return code of 4 
results. 

Error return code. See Table 3-1 below. 



8. Add a specified number of days to a Julian date to produce a new date 
Pos Argument Type Size Comments 



argl 
arg2 
arg3 



Function 

Start Date 

Days to 
Add 



Alpha 
Alpha 
Integer 



2 
5 
4 



arg4 New Date Alpha 



arg5 Ret. Code Integer 4 



Value is J + 

Supplied by user program. 

Supplied by user program. Must be in the 
range of -36524 to +36525. If outside that 
range, a return code of 8 results. 

Returned by subroutine. If the new date is in 
the 1 9th or 2 1 st century, a return code of 4 
results. 

Error return code. See Table 3-1 below. 



9. Determine the day of the week from a date in Gregorian format 
Pos Argument Type Size Comments 

Alpha 2 



argl 
arg2 
arg3 



Function 

Date 

Day of 
Week 



Alpha 
Alpha 



6 
9 



arg4 Ret. Code Integer 4 



Value is GD 

Supplied by user program. 

Returned by subroutine. The day is up- 
percase and left-justified. 

Error return code. See Table 3-1 below. 
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10. 

Pos 

argl 
arg2 
arg3 



Determine the day of the week from a date in Julian format 

Argument Type Size Comments 

Function Alpha 2 

Date Alpha 5 

Alpha 9 



Value is JD 

Supplied by user program. 



Day of 
Week 



Returned by subroutine. The day is 
uppercase and left-justified. 



arg4 Ret. Code Integer 4 Error return code. See Table 3-1 below. 

NOTE 

The subroutine assumes that all dates provided by the user program are in the 20th cen- 
tury If the subroutine computes a date that is not in the 20th century a return code of 4 
results. If the program then uses that date as an input argument to a subsequent call to 
the subroutine, DATE assumes that the date is in the 20th century 



Table 3- 1 . DATE Error Return Codes 



Return 
Code 


4 

8 



Meaning 

Successful operation. 

The result (for G+ and J+ only) is a year in either the 1 9th 
(1800-1899) or 2 1st century (2000-2099). 
Invalid input value or format. 
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DATE Subroutine — A COBOL Example 



This program returns the date one day before a specified Gregorian date by adding -1 to the speci- 
fied date. Since COBOL cannot accept negative integer data, the program uses the method explained 
in Section 2.2.2 for passing small negative integers. 



000100 

000200 

000300 

000400 

000500 

000600 

000700' 

000800 

000900 

001000 

001100 

001200 

001300 

001400 

001500 

001600 

001700 

001800 

001900 

002000 

002100 

002200 

002300 

002400 

002500 

002600 

002700 

002800 

002900 

003000 

003100 

003200 



VALUE ZERO. 
BINARY. 



IDENTIFICATION DIVISION. 

PROGRAM-ID. DATEC. 

ENVIRONMENT DIVISION. 

DATA DIVISION. 

WORKING-STORAGE SECTION. 

77 FUNCTION PIC X(2) VALUE "G+". 

THE NEXT ITEM IS THE INPUT DATE. IT IS INITIALIZED IN THE 

PROCEDURE DIVISION. 

77 START-DATE PIC X(6). 

77 ADD-DAYS PIC S9(4) VALUE -0001. 

IN THE PROCEDURE DIVISION, ADD-DAYS IS MOVED TO THE LOW-ORDER 

TWO-BYTES OF THE FOLLOWING ITEM IN ORDER TO BE PASSED TO THE 

SUBROUTINE. 

INTEGER-DAYS. 

03 FILLER USAGE IS BINARY 

03 HALFW0RD-DAYS USAGE IS 

END-DATE PIC X(6). 

RETURN-KODE. 

03 FILLER USAGE IS BINARY VALUE ZERO. 

03 RETURNED USAGE IS BINARY. 
PROCEDURE DIVISION. 
MAIN-PARAGRAPH. 

ACCEPT START-DATE. 
•THE NEXT STATEMENT PROPAGATES THE NEGATIVE SIGN ACROSS THE TOP 
*HALF OF INTEGER-DAYS, AS EXPLAINED IN SECTION 2.2.2. 

MOVE HIGH-VALUES TO INTEGER-DAYS. 

MOVE ADD-DAYS TO HALFWORD-DAYS . 

CALL "DATE" USING FUNCTION, START-DATE, INTEGER-DAYS, 
END-DATE, RETURN-KODE. 

IF RETURNED = 0, DISPLAY "END-DATE IS " END-DATE 
ELSE DISPLAY "RETURN-CODE = " RETURNED. 

STOP RUN. 



01 



77 
01 
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DATE Subroutine — A FORTRAN Example 

This example gets the current system date and time, and converts a date in Gregorian format to 
Julian format. 

L0GICAL*1 LABELU5), JDATE(5) 

REAL*8 GDATE 
C THE HD FUNCTION GETS THE DATE AND TIME IN A SPECIFIC FORMAT 

CALL DATECHD' .LABEL) 

WRITE(O.lOl) LABEL 
C THE GJ FUNCTION CONVERTS DATE IN GREGORIAN TO JULIAN FORMAT 
C THE NEXT STATEMENT SHOWS ANOTHER WAY TO SPECIFY 
C THE VALUE OF THE FIRST ARGUMENT 

ARG1 = 'GJ' 
C THE STARTING DATE IS APRIL 24, 1981 IN GREGORIAN FORMAT 

GDATE = '810424' 

CALL DATE (ARG1, GDATE, JDATE, IRET) 
C TEST RETURN CODE FOR ERRORS 

IF (IRET .EQ. 0) GO TO 1 
C ERROR PROCESSING 

WRITE(0,102) IRET 

GO TO 99 
C NO ERROR IN SUBROUTINE OPERATION 
1 WRITE(0,103) GDATE, JDATE 

101 FORMAT ( IX ,45A1) 

102 FORMAKIX, 'ERROR -RETURN CODE = ' , 13) 

103 FORMAKIX, 'GREGORIAN DATE = ' , A8/ 

IX, 'JULIAN DATE = ' , 5A1/) 

99 PAUSE 
END 



The output from this program is as follows: 

FRIDAY APRIL 24, 1981 11:31 AM 

GREGORIAN DATE = 810424 
JULIAN DATE = 81114 

PAUSE: 
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DAY 



FUNCTION 

Computes the day of the week that corresponds to any user-supplied date in the 20th 
century. 



USAGE (arg1,arg2) 

Pos Argument Type Size Comments 

argl Date Alpha 6 Provided by the user program, in the format 

YYMMDD. 

arg2 Day of Integer 4 Returned by the subroutine. Range from 1 to 

week 7, corresponding to 1 =Sunday, 2=Monday, 

... 7=Saturday. 
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DAY Subroutine — A COBOL Example 

This program accepts a date in Gregorian format for any day in the 20th century and returns the day 
of the week as an integer. 

000100 IDENTIFICATION DIVISION. 

000200 PROGRAM-ID. DAYC . 

000300 ENVIRONMENT DIVISION. 

000400 DATA DIVISION. 

000500 WORKING-STORAGE SECTION. 

000600 77 GREG-DATE PIC X(6). 

000700*AS EXPLAINED IN SECTION 2.2.2, COBOL ACCEPTS HALFWORD INTEGERS 

000800*ONLY. DEFINE A FOUR-BYTE GROUP ITEM TO BE COMPOSED OF TWO 

000900'HALFWORD-BINARY, ELEMENTARY ITEMS, AND USE THE LOW-ORDER TWO 

001000*BYTES FOR THE INTEGER. 

001100 01 DAY-HOLDER. 

001200 03 FILLER USAGE IS BINARY VALUE ZERO. 

001300 03 DAY-0F-WEEK USAGE IS BINARY. 

001400 PROCEDURE DIVISION. 

001500 MAIN-PARAGRAPH. 

001600 ACCEPT GREG-DATE. 

001700 CALL "DAY" USING GREG-DATE, DAY-HOLDER. 

001800 DISPLAY "DAY OF WEEK IS " DAY-OF-WEEK. 

001900 STOP RUN. 
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DISMOUNT 

FUNCTION 

Initiates a dismount of a mounted volume (disk or tape). 



USAGE (arg1,...,arg4) 
Pos Argument Type 

arg! Volume Alpha 



arg2 



arg3 



Device 
Type 



Nodisplay 
Option 



Alpha 



Alpha 



Size Comments 



6 
1 



arg4 Ret. Code Integer 4 



Name of volume to be dismounted. 

Device type: 

D = Disk (default) 

T = Tape 
Optional. Must be included if arg3 is present. 

Indicates whether or not to display the dis- 
mount screen at the user's workstation: 

N = No display 

Blank = Display (default) 
Optional. If present, arg2 must be included. 

Error return code. See Table 3-2 below. 



NOTE 



For FORTRAN programs, the name of this subroutine must be specified as DISMNT. 



Table 3-2. DISMOUNT Error Return Codes 



Return 

Code Meaning 

Successful dismount. 

4 Input volume name blank. 

8 Volume not found. 

1 2 Volume cannot be dismounted. 

1 6 Device detached. 

20 Volume in use by a user or the operating system. 

24 Volume reserved by another user. 

28 GETMEM failure (no more segment space). 

32 Device reserved by another task. 
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DISMOUNT Subroutine - A BASIC Example 



This program calls the DISMOUNT subroutine to dismount a volume indicated by the user. 

000100DIM VOLUMES 06 

000200DIM DEVICES 04 

000201DEVICES = "DISK" 

000202LOOP: 

000203GOSUB DISPLAYIT 

000204GOSUB D0DISM0UNT 

000205GOTO LOOP 

000210DISPLAYIT: 

000360ACCEPT 

000410 AT (01,24), 

000460"Demonstration of DISMOUNT Subroutine", 

000510 AT (07,03), 

000560"Input the name of the volume that you wish to dismount. The retu 

000610 rn code' ' , 

000660 AT (08,03), 

000710"from DISMOUNT will then appear.", 

000760 AT (10,11), 

000810"VOLUME =" , 

000860 AT (10,28), VOLUMES , CH(06), 

000910 AT (11,11), 

000960"DEVICE =" , 

001010 AT (11,28), DEVICES , CH(04), 

001060 AT (11,37), 

001110"(DISK, TAPE)" , 

001160 AT (13,11), 

001210"RETURN CODE =" , 

001260 AT (13,28), RETURNC0DE% , PIC(##), 

001310 AT (16,30), 

001360"Press ENTER to continue." 

002010RETURN 

002100 

002110DODISMOUNT 

002200 CALL "DISMOUNT" ADDR (VOLUMES , DEVICES , RETURNC0DE%) 

002210RETURN 
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DISMOUNT Subroutine — A COBOL Example 



This sample program calls DISMOUNT to dismount a disk volume called FLOPPY. 

000100 IDENTIFICATION DIVISION. 

000200 PROGRAM-ID. DSMOUNTC. 

000300 ENVIRONMENT DIVISION. 

000400 DATA DIVISION. 

000500 WORKING-STORAGE SECTION. 

000600 77 VOLUME-NAME PIC X(6) VALUE "FLOPPY". 

000700*AS EXPLAINED IN SECTION 2.2.2, COBOL ACCEPTS HALFWORD INTEGERS 

000800*ONLY. DEFINE A FOUR-BYTE GROUP ITEM TO BE COMPOSED OF TWO 

000900*HALFWORD-BINARY, ELEMENTARY ITEMS, AND USE THE LOW-ORDER TWO 

001000*BYTES FOR THE INTEGER. 

001100 01 RETURN-KODE. 

001200 03 FILLER USAGE IS BINARY VALUE ZERO. 

001300 03 ERROR-CODE USAGE IS BINARY. 

001400 PROCEDURE DIVISION. 

001500 MAIN-PARAGRAPH. 

001600 CALL "DISMOUNT" USING VOLUME-NAME, RETURN-KODE. 

001700 IF ERROR-CODE NOT EQUAL ZERO DISPLAY "ERROR-CODE = " 

001800 ERROR-CODE. 

001900 STOP RUN. 
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DISMOUNT Subroutine - AN RPG II Example 



This program instructs DISMOUNT to dismount the disk volume VOL1 1 1 . The program checks the 
subroutine return code and tells the user whether the dismount was successful. The program displays 
a return code whose value is greater than 0. 



00100FDISPLAY DD 

00200C 

00201C* 

00203C* 

00205C* 

00210C 

00220C 

00240C 

00242C* 

00245C* 

00247C* 

00250C 

00255C 

00260C 

00270C 

00271C* 

00272C* 

00274C* 

00275C RCODE 

00280C 99 

00282C N99 

00284C 



: WS 

ACCPTSCR1 
" PREPARE PARAMETERS TO PASS TO RPGCALL MACRO 



MOVE 'V0L111' VOL 
MOVE 'D' TYPE 

Z-ADDO RCODE 

EXIT TO RPGCALL MACRO 



6 

1 
40 



EXIT RPGDMT 
RLABL 
RLABL 
RLABL 

** CHECK RETURN CODE 



COMP 
ACCPTSCR3 
ACCPTSCR2 
SETON 



VOL 

TYPE 

RCODE 



99 



LR 



00300WSCR1 

00400W 

00500W 

00600WSCR2 

00700W 

00800W 

00900WSCR3 

01000W 

01100W 

01200W 

01300W 



0707 
0729 

0707 
0907 

0707 
0907 

0921RC0DE 
1107 



'PRESS ENTER TO DISMOUN' 
'T DISK VOL111. ' 

'DISMOUNT SUCCESSFUL. ' 
'PRESS ENTER TO END JOB' 

'DISMOUNT UNSUCCESSFUL.' 
'RETURN CODE = ' 

'PRESS ENTER TO END JOB' 



RPGDMT: 



RPGCALL NAME=RPGDMT,CALL=DISMOUNT,VOL,TYPE, (RCODE, 4, F) 



DISMOUNT -4 



EXPAND 



FUNCTION 

Converts a character string from compressed format to external format. EXPAND 
removes the control characters used to indicate repeated characters and produces text 
in noncompressed form. 



USAGE (argl arg5) 

Pos Argument Type 



argl 
arg2 

arg3 
arg4 



Input 

Input 

Length 

Output 

Output 
Length 



Size Comments 



Alpha var 

Integer 4 

Alpha var 

Integer 4 



arg5 Ret. Code Integer 4 



String to be expanded. 

Length of input string. Must be nonnegative 
and not greater than 2048. 

Receiver that contains the expanded string. 

Maximum length of output string. Must be 
between and 2048, and is reduced by the 
subroutine to reflect the actual length of the 
resulting character string. 

Error return code. See Table 3-3 below. 

If the return code is nonzero, the value of the 

output string is unpredictable. 



NOTES 

1 . The operation of this subroutine is identical to the process used by the XPAND 
Assembler instruction, used by DMS to expand records. 

2. This subroutine is the inverse of the COMPRESS subroutine. 

3. The EXPAND subroutine example appears after the description of the COMPRESS 
subroutine. 



Table 3-3. EXPAND Error Return Codes 



Return 
Code 


4 
8 



Meaning 

Successful. 

Maximum output length too short. 

Bad compression information was found in the input string. 
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EXTRACT 



FUNCTION 

Provides information about the system and the program user. The available information 
appears below. 

USAGE (keyl, red, key2, rec2 keyn, recn) 

The argument list includes keyword-receiver pairs. A keyword must be immediately fol- 
lowed by a receiver. Each keyword selects particular information to be extracted about 
the system or the user, which the subroutine returns in the receiver. In a few cases, the 
user program must provide input in part of the receiver. 

Each keyword is a 2-byte alpha value. A discussion of keywords, receivers, and the infor- 
mation extracted follows. 



Keyword 

A? 

BP 
C 



Recr 
Type 

Alpha 



Integer 
Alpha 



Recr 
Size 

256 



4 
16 



C# 



Alpha 



CL 


Alpha 


8 


CV 


Alpha 


6 


D 


Alpha 


24 



Receiver 
Value 

ASCII-to-EBCDIC translation table. Presents EBCDIC 
characters corresponding to ASCII characters X'OO' 
to XTF. 

Number of available segment 2 buffer pages. 

Cluster information. Bytes 1 -2 must contain the 
device address of the workstation, in binary. The sub- 
routine returns the following information: 

Byte 1 -2— Device address of archiver diskette 
(0 if none). 
3-16— Binary zeroes (reserved). 

CPU ID number (CO, and microcode version (MM), in 
the form CCMM (hexadecimal digits). 

Current program library. 

Current program volume. 

Device information. The first byte must contain the 
device address, in binary. The subroutine fills the 
receiver with the following: 
Byte 1 — Device class. 

2 — Device type. 
3-4— Usage: 

EX = Exclusive. 
SH = Shared. 
DT = Detached. 
5-8 — Task identifier of device owner, or 
-1 if none. 
9-14— Volume serial number of removable 
volume (disk or tape only). Blank if 
nothing mounted. 
1 5-20— Volume serial number of fixed 

volume (disk only). Blank if nothing 
mounted. 
2 1 -24— Binary zeroes (reserved). 
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Recr Recr Receiver 

Keyword Type Size Value 

D@ Integer 4 Disk I/O count since logon. 

DC Integer 4 Number of devices in the system. 

DK Integer 4 System diskette device number. 

DL Alpha var Returns a list of device addresses of the specified 

device type. The first 2 bytes must contain the device 
type and the number of device addresses to be 
returned (specified in binary). 
Byte 1 — Device type: 

X'01' = workstation 
X'02' = magnetic tape 
X'03' = disk 
X'04' = printer 
X'05' = telecommunications 
Byte 2 — Number of device addresses to be 

returned (0-253). The receiver size 
must be at least this value + 2. 
The receiver contains the following information: 
Byte 1 — Total number of devices in the 

specified class. 
Byte 2— Number of device addresses sup- 

plied. 
Rest — Device address list (1 byte for each 

device address). 

DV Alpha 24 Disk volume information. Bytes 1 -6 must contain the 

volume name. The receiver contains the following 
information: 

Byte 1 — Device address, or - 1 if not 

mounted. 
2 — Volume type: 
F = Fixed 
R = Removable 
Blank = Not mounted 
3-4— Label type: 

SL = Standard label 
NL = No label 
Blank = Not mounted 
5-6— Usage: 

SH = Shared 
RR = Restricted removal 
EX = Exclusive 
Blank = Not mounted 
7-10— Task identifier of volume mounter, 
or-1 if none. 
1 1-12— Blocks per cylinder. 
1 3-14— Maximum transfer in bytes. 
15-16— Cylinders per volume. 
17-18— Cylinders per physical volume, 
including bad or unused blocks. 
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Recr Recr Receiver 

Keyword Type Size Value 

1 9-20— Number of files open on this 

volume. 
21-24— Binary zeroes (reserved). 

Number of clock units in one day. 

Elapsed time in 1/1 00 seconds. 

EBCDlt-ASCII translation table. 

Default file protection class. 

Default printer form number (0-254). 

A/C line frequency. 

Current user's ID. 

Default input library. 

Default input volume. 

Background job default class (A-Z). 

Background job default time limit in seconds. 

Background job name. 

Background job default status (R=Run, H=Hold). 

Data Link Processor (DLP) status. The first 2 bytes 
must contain the device address, in binary. The 
receiver contains the following information: 
Byte 1 — Device status flag : 

X'80' if open 
X'40' if reserved 
Zero otherwise 
2-4— Task number of the task that 

reserved the DLP, zero if device is 
unreserved. 
5-8— Name of the DLP on which the 
device is SYSGENed. 

Integer 4 Default lines-per-page for printer output. 

Alpha 38 Data Link Processor (DLP) information. Bytes 1 -4 

must contain the DLP name. The receiver contains 
the following information: 

Byte 1-4— Bit map of devices on DLP. 
5-6— First device on DLP. 
7 — Type of DLP: 

1 =22V06-1 

2 = 22V06-2 

3 = 22V06-3 

8— Number of lines controllable by DLP. 

9— Microcode file status: 
X'OO' if stopped 
X'80' if loaded 

10-12— Reserved for future use. 



DY 


Integer 


4 


E: 


Integer 


4 


E? 


Alpha 


256 


FC 


Alpha 


1 


FN 


Integer 


4 


HZ 


Integer 


4 


ID 


Alpha 


3 


IL 


Alpha 


8 


IV 


Alpha 


6 


JC 


Alpha 


1 


JL 


Integer 


4 


JN 


Alpha 


8 


JS 


Alpha 


1 


L 


Alpha 


8 



LI 
LN 
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Keyword 



Recr 
Type 



Recr 
Size 



ME 

MF 

MR 

MW 

NA 

NR 

0@ 

OL 

OV 

P+ 

P- 

P: 

P@ 

PC 

PL 

PM 

PR 

PV 

RL 

RV 

S# 

s+ 
s- 

S2 
SL 
SS 



Alpha 


4 


Integer 


4 


Alpha 


4 


Alpha 


4 


Alpha 


24 


Integer 


4 


Integer 


4 


Alpha 


8 


Alpha 


6 


Integer 


4 


Integer 


4 


Integer 


4 


Integer 


4 


Alpha 


1 


Alpha 


8 


Alpha 


1 


Integer 


4 


Alpha 


6 


Alpha 


8 


Alpha 


6 


Alpha 


6 


Integer 


4 


Integer 


4 


Integer 


4 


Alpha 


8 


Integer 


4 



Receiver 
Value 

1 3-20— Microcode file name, if not loaded. 
21-28— Microcode library name, if not 

loaded. 
29-34— Microcode volume name, if not 
loaded. 
35— Reservation status of DLP: 
m X'80' if reserved 

X'OO' if not reserved 
36-38— Task number of task that reserved 
DLP. 

Execute-access mask currently in effect. 

Maximum number of files that the user can open, in 
addition to those already opened. 

Read-access mask currently in effect. 

Write-access mask currently in effect. 

Current user's name (from Userlist). 

Total nonresident physical area, in bytes. 

Count of "other" I/O transactions (not involving disk, 
workstation, printer, tape). 

Default output library. 

Default output volume. 

Program page-in count. 

Program page-out count. 

Processor time in 1 /1 00 seconds. 

Printer I/O count. 

Default print class (A-Z). 

Default program library (current). See Note 1 . 

Default print mode (S, H, K, or O). 

Default printer number (for online printing). 

Default program volume (current). See Note 1 . 

Run library (initial). See Note 1 . 

Run volume (initial). See Note 1 . 

System version number, in the form VVRRPP (Ver- 
sion, Revision, Patch). 

System page-in count. 

System page-out count. 

Segment 2 size. 

Default spool library. 

Remaining stack space. 
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Recr Recr Receiver 

Keyword Type Size Value 

SV Alpha 6 Default spool volume. 

T Alpha 48 Task information. 

Bytes 1 -4 must contain the task number, in binary. 
The receiver contains the following information: 
Byte 1 — Workstation device number 

(binary), -1 if background task. 
2-4— Current user ID for task, blank if 
none. 
5-28— Current user name for task, blank if 
none. 
29 — Type of task specified: 
B = Background 
F = Foreground 
30— Blank. 
31-48— Binary zeroes (reserved). 



T# 


Integer 


4 


Task number. 


T@ 


Integer 


4 


Tape I/O count. 


TP 


Integer 


4 


Task priority. 


TT 


Alpha 


1 


Task type: 

F = Foreground 
B = Background 



TV 



Alpha 



20 



UE 
UR 
UW 
W# 



Alpha 


4 


Alpha 


4 


Alpha 


4 


Integer 


4 



Tape volume information. Bytes 1 -6 must contain the 
volume name. The receiver contains the following 
information: 

Byte 1 — Device address, -1 if not mounted. 

2— Binary zero (reserved). 
3-4— Density in BPI, in binary: 

(556, 800, or 1 600) 
5-6— Label type: 

NL = No Label 
IL = IBM Label 
AL = ANSI Label 
Blank = Not mounted 
7-8— Usage: 

SH = Shared 
EX = Exclusive 
Blank = Not mounted 
9-12— Task identifier of tape mounter, - 1 if 
none (in integer(4) format). 
1 3-14— Current file sequence number (on 

the tape). 
1 5-20— Binary zeroes (reserved). 

Default execute-access mask for current user. 

Default read-access mask for current user. 

Default write-access mask for current user. 

This workstation's device number, -1 if none. 
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Recr 


Recr 


Receiver 


Keyword 


Type 


Size 


Value 


W@ 


Integer 


4 


This workstation's I/O count 


WL 


Alpha 


8 


Default work library. 


WV 


Alpha 


6 


Default work volume. 


XL 


Alpha 


8 


System library. 


XP 


Alpha 


8 


System paging library. 


XV 


Alpha 


6 


System volume. 


XW 


Alpha 


8 


System work library. 



NOTES 

1 . "Current" refers to the library or volume applicable to the program that contains 
the EXTRACT call. "Initial" refers to the library or volume applicable to the entire 
session. 

2. For FORTRAN programs, the name of this subroutine must be specified as 
XTRACT 
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EXTRACT Subroutine — A COBOL Example 



This program retrieves its own Segment 2 size. This size is always greater than 32767, the maximum 
size for an integer in COBOL's halfword-binary format. The program circumvents the problem (dis- 
cussed in Section 2.2.2), by calling the BASIC subroutine 4T09. 

000100 IDENTIFICATION DIVISION. 

000200 PROGRAM-ID. EXTRACTC. 

000300 ENVIRONMENT DIVISION. 

000400 DATA DIVISION. 

000500 WORKING-STORAGE SECTION. 

000600 77 KEYWORD PIC X(2) VALUE "S2". 

000700*THE NEXT ITEM RECEIVES THE SEGMENT 2 SIZE FROM EXTRACT AND 

000800*PASSES IT TO 4T09 . 

000900 01 TEMP PIC X(4) . 

001000*THE NEXT ITEM RECEIVES THE SEGMENT 2 SIZE FROM 4T09 AND RETURNS 

001100'IT TO THE COBOL PROGRAM. 

001200 01 SEG-2-SIZE PIC S9(8). 

001300 PROCEDURE DIVISION. 

001400 MAIN-PARAGRAPH. 

001500 CALL "EXTRACT" USING KEYWORD, TEMP. 

001600 CALL "4T09" USING TEMP, SEG-2-SIZE. 

001700 DISPLAY SEG-2-SIZE. 

001800 STOP RUN. 
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EXTRACT Subroutine — A FORTRAN Example 

This example calls the EXTRACT subroutine to obtain the user's ID, the default output library, and the 
number of CPU seconds used. All are displayed on the workstation. 

C 'OUTLIB' IS THE DEFAULT OUTPUT LIBRARY 

C 'ID' IS THE USER'S ID 

C 'CPUSEC IS THE NUMBER OF CPU SECONDS USED 

REAL'8 OUTLIB 

INTEGERM ID, CPUSEC 
C* CALL EXTRACT (XTRACT IN FORTRAN) WITH ID, OL, AND P: KEYWORDS 

CALL XTRACT ('ID', ID, 'OL', OUTLIB, 'P:', CPUSEC) 
C* SINCE CPUSEC RETURNS CPU USAGE IN 1/100 SECS, MUST CONVERT 

SECS = CPUSEC/100.0 

WRITE(0,101) ID, OUTLIB, SECS 
101 FORMAKIX, 'USER ID IS ', A3/ 

1 IX, 'DEFAULT OUTPUT LIBRARY IS ', A8/ 

2 IX, 'NUMBER OF CPU SECONDS IS ', F12.2) 
PAUSE 

END 
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EXTRACT Subroutine - AN RPG II Example 



This program extracts and displays the user's name and ID, the current device count, the number of 
files that the user can still open, and the number of system page-ins performed so far. 



00100FSCREEN DD F 



WS 



00101C* 

00102C* 

00103C* 

00110C 

00120C 

00200C 

00300C 

00400C 

00500C 

00600C 

00700C 

00800C 

00900C 

00910C* 

00920C* 

00930C* 

01000C 

01100C 

01200C 

01210C 

01220C 

01230C 

01240C 

01250C 

01255C 

01265C 

01275C 

01285C* 

01295C* 

01305C* 

01315C 

01355C 

01365C 



■* PREPARE PARAMETERS TO BE PASSED 



MOVE 'DC 


DC 


2 


Z-ADDO 


DCX 


40 


MOVE 'ID' 


ID 


2 


MOVE ' ' 


IDX 


3 


MOVE 'MF' 


MF 


2 


Z-ADDO 


MFX 


40 


MOVE 'NA' 


NA 


2 


MOVE ' ' 


NAX 


24 


MOVE 'S+' 


SP 


2 


Z-ADDO 


SPX 


40 



EXIT TO THE RPGCALL MACRO *** 



KG 



01455WSCR1 

01555W 

01655W 

01755W 

01855W 

01955W 

02055W 

02155W 

02255W 

02355W 

02455W 



EXIT RPGEXT 




RLABL 




DC 


RLABL 




DCX 


RLABL 




ID 


RLABL 




IDX 


RLABL 




MF 


RLABL 




MFX 


RLABL 




NA 


RLABL 




NAX 


RLABL 




SP 


RLABL 




SPX 


DISPLAY EXTRACTED INFORMATION *** 


ENBLEKG 




ACCPTSCR1 




SETON 




LR 


0707 


'USER' 




0712NAX 






0738 


'( )' 




0739IDX 






0907 


'CURRENT 


DEVICE COUNT: ' 


0930DCX 






1107 


'YOU MAY 


OPEN MORE' 


1129 


' FILES. 1 


t 


1120MFX 






1307 


'SO FAR, 


SYSTEM PA' 



EXTRACT-9 



02555W 1329 'GEINS.' 

02655W 1315SPX 

02755W 2007 'PRESS PF 16 TO EXIT. 



RPGEXT: 



RPGCALL NAME=RPGEXT,CALL=EXTRACT,DC, (DCX, 4 , F) , ID, IDX.MF, 
(MFX,4,F) .NA.NAX.SP, (SPX.4.F) 
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FIND 



FUNCTION 

Obtains one or more file, library, or volume names from complete or partial file, library, 
and volume names supplied by the user program. Also, indicates whether a specified file 
resides in a specified library and volume. 



USAGE (argl arg8) 

See the note after the argument descriptions for information about specifying the 
names of files, libraries, and volumes. 



Pos Argument Type Size 

argl File Alpha 8 



arg2 Library 



arg3 Volume 



Alpha 8 



Alpha 



arg4 Starter Integer 4 

arg5 Counter Integer 4 

arg6 Receiver Alpha var 



arg7 File 

Count 



Integer 



arg8 Receiver Alpha 1 

Type 



Comments 

File or files to be found. If blank, a library 
search is assumed. 

Library or libraries to be found. If blank, a 
volume search is assumed. 

Volume or volumes to be found. The volume 
name should not be blank. Only Standard 
Label (SL) volumes can be searched. 

Entry at which to begin listing. See Note 3. 

Maximum number of entries to be listed. The 
user provides an initial value; the subroutine 
sets this to the actual count. See Note 3. 

Entries. Each entry is 22 bytes and contains: 
Byte 1-6— Volume 

7-14— Library (can be blank) 
1 5-22— File (can be blank) 
Arg8 = A, blank, or omitted: this is the 
name or address of the variable that holds 
the requested entries. 
Arg8 = F: this must be the UFB address 
(File # in BASIC, or FD in COBOL) of a con- 
secutive file, record size 22, opened in 
Output or Extend mode. 

Actual number of eligible entries, returned 
by the subroutine. Optional, but must be pre- 
sent if arg8 is included. See Note 2. 

Type of output to be returned. 
For alpha receiver (default), specify A or 
blank. For file receiver, specify F. Optional. If 
included, arg7 must also be present. See 
arg6 description. 
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How to Specify the Names of Files, Libraries, and Volumes 

The file, library, and volume arguments can be either standard alphanumeric names, or 
masks that contain both standard characters and one or more of the special characters 
? and *. The significance of these special characters is as follows: 

? corresponds to any string of any length in the name. For example, if Library = 
?XYZ?, the subroutine returns all libraries whose names contain the string XYZ 
preceded and/or followed by any (or no) characters. 

* corresponds to a single nonblank character in the name. For example, if Library = 
", the subroutine returns all one-letter libraries in the specified volume. 

Blanks are ignored in the input arguments. Also, a completely blank input argument 
selects the next level of find. For example, blank file returns a library list, blank file and 
library returns a volume list. 

Examples of File, Library, and Volume Specifications 



File 
X 



? 

blank 

blank 



Library 

Y 

? 
?ABC? 

? 

#?PRT 

blank 



Volume 

Z 

? 
? 

VOL123 
SYSTEM 



Items Returned 

Returns X, Y, and Z if file X exists in library Y on volume 
Z; otherwise, returns nothing. 

All one-letter file names. 

All file names in every library whose name contains 
ABC. 

All files on volume VOL1 23. 

All print library names on volume SYSTEM. 

All volume names currently mounted on the system. 



NOTES 

1 . If the subroutine cannot read the VTOC of a volume for any reason, it ignores that 
volume. 

2. Argument 7 provides the total number of entries found, while argument 5 indicates 
how many entries are to be returned in the receiver. If the program includes argu- 
ment 7 and if it is larger than argument 5, the subroutine might take more time to 
execute. 

3. The program can use arguments 4 and 5 together to successively output a large 
number of qualified entries. For example, if Starter= 1 and Counter=1 00, the first 
100 entries are returned to the receiver. Then, if Starter is incremented to 1 01 and 
Counter remains at 1 00, a second use of the subroutine results in returning the 
second 1 00 entries. Each increment requires a separate call to FIND and adds time 
to the process. 
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FIND Subroutine — A COBOL Example 



This program allows the user to retrieve the names of files, libraries, or volumes on the system. The 
program displays output on the workstation. 

000100 IDENTIFICATION DIVISION. 

000200 PROGRAM-ID. FINDC. 

000300 ENVIRONMENT DIVISION. 

000400 DATA DIVISION. 

000500 WORKING-STORAGE SECTION. 

000600 77 FILE-NAME PIC X(8). 

000700 77 LIB-RARY PIC X(8). 

000800 77 VOL-UME PIC X(6) . 

000900*AS EXPLAINED IN SECTION 2.2.2, COBOL ACCEPTS HALFW0RD INTEGERS 

001000*ONLY. DEFINE A FOUR-BYTE GROUP ITEM TO BE COMPOSED OF TWO 

001100*HALFWORD-BINARY, ELEMENTARY ITEMS, AND USE THE LOW-ORDER TWO 

001200*BYTES FOR THE INTEGER. TO PASS THE INTEGER TO THE SUBROUTINE, 

001300 # INITIALIZE THE HIGH-ORDER BYTES TO ZERO. 

001400 01 STARTER. 

001500 03 FILLER USAGE IS BINARY VALUE ZERO. 

001600 03 START-INTEGER USAGE IS BINARY VALUE 1. 

001700 01 COUNTER. 

001800 03 FILLER USAGE IS BINARY VALUE ZERO. 

001900 03 COUNT-INTEGER USAGE IS BINARY. 

002000 77 RECEIVER PIC X(110). 

002100 01 ENTRIES. 

002200 03 FILLER USAGE IS BINARY VALUE ZERO. 

002300 03 ENTRY-COUNT USAGE IS BINARY. 

002400 PROCEDURE DIVISION. 

002500 FIRST-PARAGRAPH. 

002600 ACCEPT FILE-NAME, LIB-RARY, VOL-UME. 

002700 IF FILE-NAME = "!" GO TO EXIT-PARAGRAPH. 

002800'COUNT-INTEGER RECEIVES THE ACTUAL NUMBER OF ENTRIES RETURNED, 

002900 # IF LESS THAN THE ORIGINAL SPECIFICATION. THUS IT MUST BE 

003000 # RE-INITIALIZED FOR THE SUBROUTINE TO BE CALLED AGAIN. 

003100 MOVE 5 TO COUNT-INTEGER. 

003200 SECOND-PARAGRAPH. 

003300 PERFORM CALL-PARAGRAPH. 

003400'START-INTEGER IS INCREMENTED EACH TIME THROUGH THE LOOP. WHEN 

003500*IT BECOMES GREATER THAN THE NUMBER OF AVAILABLE ENTRIES, CONTROL 

003600*RETURNS TO THE FIRST PARAGRAPH. 

003700 IF START-INTEGER GREATER THAN ENTRY-COUNT, MOVE 1 TO 

003800 START-INTEGER, PERFORM FIRST-PARAGRAPH. 

003900 PERFORM SECOND-PARAGRAPH. 

004000 CALL-PARAGRAPH. 

004100 MOVE SPACES TO RECEIVER. 

004200 CALL "FIND" USING FILE-NAME, LIB-RARY, VOL-UME, STARTER, 

004300 COUNTER, RECEIVER, ENTRIES. 

004400 DISPLAY RECEIVER. 

004500 DISPLAY "ENTRY-COUNT = "ENTRY-COUNT, 

004600 " START-INTEGER = "START-INTEGER, 

004700 " COUNT-INTEGER = "COUNT-INTEGER. 

004800 ADD 5 TO START-INTEGER. 

004900 EXIT-PARAGRAPH. 

005000 STOP RUN. 
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FIND Subroutine - A FORTRAN Example 

This example finds files, libraries, and volumes on the disk depending on the input that the user 
enters. The program displays output on the workstation. 

C 'LIBS' CONTAINS THE NAMES OF LIBRARIES 

C 'IFILE', 'ILIB', 'IVOL' ARE ENTERED BY THE USER 

C EVERY RECORD MUST BE 22 BYTES LONG 

C LIBS(22,100) provides 100 RECORDS, EACH 22 BYTES LONG 

L0GICAL*1 LIBS(22,100) 

REAL'8 IFILE, ILIB, IVOL 

ICOUNT = 100 

WRITE(0,103) ' FILE?' 

READ(0,103) IFILE 

WRITE(0,103) ' LIB?' 

READ(0,103) ILIB 

WRITE(0,103) ' VOL?' 

READ(0,104) IVOL 
C 
C CALL FIND TO PROVIDE NAMES DEPENDING ON WHAT THE OPERATOR ENTERED 

CALL FINDdFILE, ILIB, IVOL, 1, ICOUNT, LIBS) 
C 

WRITE(0,102) ICOUNT 

DO 10 1=1,5 

WRITE(O.lOl) (LIBS(J,I),J=1,22) 
10 CONTINUE 

101 FORMAT ( IX, 22A1) 

102 F0RMAT(1X,I5) 

103 FORMAT (A8) 

104 FORMAT (A6) 
PAUSE 

END 
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FLOPIO 



FUNCTION 



Performs the following I/O operations with a nonlabeled (NL) diskette: 

OPEN the diskette as a file 

CLOSE the diskette 

READ or READ-HOLD from the diskette 

WRITE or REWRITE to the diskette 

Find the status of a specified diskette 



USAGE (argl , arguments) 

Arg1 determines the I/O function that the subroutine performs and the number and 
nature of the additional arguments. 

1 . OPEN the diskette as a file 



Pos Argument Type 

argl Function Alpha 2 

arg2 Open Mode Alpha 2 



Size Comments 



arg3 


Prname 


Alpha 


8 


arg4 


Volume 


Alpha 


6 


arg5 


Record 
Size 


Integer 


4 



arg6 Ret. Code Integer 4 



Value is OP 

Mode in which the diskette is open: 
IN = Input mode 
IO = IO mode 
OU = Output mode 

User-supplied parameter reference name for 
the file. Only one file can be open at a time. 

Name given the diskette when mounted. 

Size of NL diskette records: 

4096 for 2200 diskettes (default) 
256 for VS/WP and VS diskettes 
If omitted, the last value used is assumed. 
See Note 3. 

Error return code. 

= Successful open 

4 = Not an NL diskette 
If neither, the subroutine returns the follow- 
ing information from the UFB: 

Byte 1 — UFBFS2, the second byte 

of the file status code 

2- UFBXCODE, extended 
open exit code 

3- UFBF2, open mode flag 

4- Hex '08' 

Refer to the VS Operating System Services 
for a complete explanation of each of these 
bytes. 
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Arguments 3 to 5 are optional. If the program uses an argument, all the previous argu- 
ments must be included. 

If argument 3 or 4 is omitted or contains only hexadecimal zeroes, the prname and 
volume names currently in the UFB are moved to these fields. 



2. CLOSE the previously opened diskette 

Pos Argument Type Size Comments 

argl Function Alpha 2 Value is CL 

arg2 Ret. Code Integer 4 Error return code. See Table 3-4 below. A 

nonzero value is the file status code for the 
last WRITE to the file. 



3. READ or READ-HOLD from the diskette 

Pos Argument Type Size Comments 

arg 1 Function Alpha 2 



arg2 

arg 3 
arg4 

4. 

Pos 

argl 

arg2 
arg3 



Record 
Number 



Integer 



Buffer Alpha 256 

Ret. Code Integer 4 

WRITE or REWRITE to the diskette 



Type of read to be performed: 
RE = READ 
RH = READ-HOLD 

Sector number to be read. The first sector is 
1 . A value of is equivalent to a READ NEXT. 

Receiver for the returned record. 

Error return code. See Table 3-4 below. 



Argument Type 

Function Alpha 



Buffer 



Alpha 



Ret. Code Integer 



Size Comments 

2 WRITE or REWRITE: 

WR = WRITE 
RW = REWRITE 

256 Buffer containing the record to be written. 
See Note 3 for information about its length. 

4 Error return code. See Table 3-4 below. 



Find the status of a specified diskette 



Pos Argument Type 



argl 
arg2 



Function 
Volume 



Alpha 
Alpha 



Size Comments 

2 Value is Fl 

6 Name assigned the diskette when mounted. 

If it contains hexadecimal zeroes or is omit- 
ted, the subroutine assumes the volume 
name currently in the UFB, and replaces the 
hexadecimal zeroes with that volume name. 
Must be included if arg3 is present. 
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Pos Argument Type Size Comments 

arg3 Diskette Alpha 2 I/O status of the diskette relative to the cur- 

Status rent program, returned by the subroutine: 

OU = Open for output 
IN = Open for input 
10 = Open for I/O 
CL = Not opened by FLOPIO 
Optional. If present, arg2 must be included. 

arg4 Ret. Code Integer 4 Error return code: 

= Diskette found 
4 = Not an NL diskette 
8 = Diskette not mounted 



NOTES 

1 . Input mode allows READ only. 10 mode allows READ, READ-HOLD, and REWRITE. 
Output mode allows WRITE only. 

2. In all cases, an invalid sequence of functions, such as closing an unopened file or 
doing a READ in input mode, causes the user program to be cancelled. 

3. An NL diskette is assumed to have 256-byte sectors. That is the record size used 
in all READs, REWRITES, and WRITEs. The size specified for the OPEN command 
serves only to tell the subroutine whether the sectors are in 2200, VS/WP, or VS 
order. On VS/WP and VS diskettes, consecutively numbered sectors are physically 
consecutive and are processed sequentially, starting from the outermost track, 1 6 
sectors per track. On a 2200 diskette, consecutively numbered sectors are located 
four physical sectors apart within a track. FLOPIO processes the sectors in 
numeric, rather than physically consecutive, order. 

In Output mode, data is physically written to the diskette in 4096-byte blocks (one 
track). Therefore, if a multiple of 16 sectors is not written, the unwritten sectors 
contain undefined data. If this is not desirable, the programmer can use 
READ/REWRITE in IO mode. This method, however, is noticeably slower. 



Table 3-4. FLOPIO Error Return Codes 



Return 

Code Meaning 

Successful operation. 

1 End-of -diskette encountered (for READ NEXT or READ HOLD). 

23 Invalid record number (for READ or READ HOLD). 

30 Hardware error. 

34 End-of-diskette encountered (for WRITE). 
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FLOPIO Subroutine - A COBOL Example 

This program opens a nonlabeled diskette volume, writes two records to the diskette, closes it, opens 
it again, reads and displays the two records, and closes the diskette. 

000100 IDENTIFICATION DIVISION. 

000200 PROGRAM-ID. FLOPIOC. 

000300 ENVIRONMENT DIVISION. 

000400 DATA DIVISION. 

000500 WORKING-STORAGE SECTION. 

000600 77 FUNCTION PIC X(2). 

000700 77 OPEN-MODE PIC X(2) VALUE "OU". 

000800 77 PRNAME PIC X(8) VALUE "FLOPIO". 

000900 77 VOLUME-NAME PIC X(6) VALUE "FLOPPY". 

001000*AS EXPLAINED IN SECTION 2.2.2, COBOL ACCEPTS HALFW0RD INTEGERS 

001100 # ONLY. DEFINE A FOUR-BYTE GROUP ITEM TO BE COMPOSED OF TWO 

001200*HALFWORD-BINARY, ELEMENTARY ITEMS, AND USE THE LOW-ORDER TWO 

001300 # BYTES FOR THE INTEGER. TO PASS AN INTEGER TO THE SUBROUTINE, 

001400*INITIALIZE THE HIGH-ORDER BYTES TO ZERO. 

001500 01 RECORD-SIZE. 

001600 03 FILLER USAGE IS BINARY VALUE 0. 

001700 03 R-SIZE USAGE IS BINARY VALUE 256. 

001800 01 RETURN-KODE. 

001900 03 FILLER USAGE IS BINARY VALUE ZERO. 

002000 03 ERROR-CODE USAGE IS BINARY. 

002100 77 BUF-FER PIC X(256) VALUE SPACE. 

002200 01 RECORD-NUMBER. 

002300 03 FILLER USAGE IS BINARY VALUE 0. 

002400 03 RECORD-COUNTER USAGE IS BINARY. 

002500 PROCEDURE DIVISION. 

002600 MAIN-PARAGRAPH. 

002700 PERFORM OPEN-PARAGRAPH. 

002800 PERFORM WRITE-PARAGRAPH VARYING RECORD-COUNTER FROM 1 BY 1 

002900 UNTIL RECORD-COUNTER EQUAL 3. 

003000 PERFORM CLOSE-PARAGRAPH. 

003100 MOVE "IN" TO OPEN-MODE. 

003200 PERFORM OPEN-PARAGRAPH. 

003300 PERFORM READ-PARAGRAPH VARYING RECORD-COUNTER FROM 1 BY 1 

003400 UNTIL RECORD-COUNTER EQUAL 3. 

003500 PERFORM CLOSE-PARAGRAPH. 

003600 STOP RUN. 

003700 OPEN-PARAGRAPH. 

003800 DISPLAY "I AM IN THE OPEN-PARAGRAPH." 

003900 MOVE "OP" TO FUNCTION. 

004000 CALL "FLOPIO" USING FUNCTION, OPEN-MODE, PRNAME, VOLUME-NAME, 

004100 RECORD-SIZE, RETURN-KODE. 

004200 IF ERROR-CODE NOT EQUAL GO TO ERROR-PARAGRAPH. 
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004300 WRITE-PARAGRAPH. 

004400 DISPLAY "I AM IN THE WRITE-PARAGRAPH." 

004500 IF RECORD-COUNTER = 1 MOVE "THE FIRST RECORD" TO BUF-FER 

004600 ELSE MOVE "THE SECOND RECORD" TO BUF-FER. 

004700 MOVE "WR" TO FUNCTION. 

004800 CALL "FLOPIO" USING FUNCTION, BUF-FER, RETURN-KODE. 

004900 IF ERROR-CODE NOT EQUAL ZERO GO TO ERROR-PARAGRAPH. 

005000 READ-PARAGRAPH. 

005100 DISPLAY "I AM IN THE READ-PARAGRAPH." 

005200 MOVE "RE" TO FUNCTION. 

005300 CALL "FLOPIO" USING FUNCTION, RECORD-NUMBER, BUF-FER, 

005400 RETURN-KODE. 

005500 IF ERROR-CODE NOT EQUAL ZERO GO TO ERROR-PARAGRAPH. 

005600 DISPLAY BUF-FER. 

005700 CLOSE-PARAGRAPH. 

005800 DISPLAY "I AM IN THE CLOSE-PARAGRAPH." 

005900 MOVE "CL" TO FUNCTION. 

006000 CALL "FLOPIO" USING FUNCTION, RETURN-KODE. 

006100 IF ERROR-CODE NOT EQUAL ZERO GO TO ERROR-PARAGRAPH. 

006200 ERROR-PARAGRAPH. 

006300 DISPLAY "ERROR CODE = " ERROR-CODE. 

006400 STOP RUN. 
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GETPARM 

FUNCTION 

Provides the ability to generate parameter requests in a higher-level language program. 

USAGE 

The GETPARM argument list consists of the following sets of arguments. Some are 
optional, and some are repeatable. 

The GETPARM Definition argument sequence: GETPARM Type, Form, Prname, PF Key 
Receiver, Message ID, Message Issuer, Message Line Count, Message Text, 
Message Text Length 

The Keyword Field type argument sequence: Specification Type, Keyword, Value, 
Length, Row Flag, Row, Column Flag, Column, Data Type 

The Text Field type argument sequence: Specification Type, Text, Text Length, Row 
Flag, Row, Column Flag, Column 

The PF Key Mask argument sequence: Specification Type, PF Key Mask 

The ENTER Flag specification: Specification Type 

Each GETPARM argument sequence is described below. 
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GETPARM Definition Arguments 

The following mandatory sequence of nine arguments is included only once in the argu- 
ment list. 



Pos Argument Type 
argl Type Alpha 



arg2 Form 



Alpha 



arg3 


Prname 


Alpha 


8 


arg4 


PFKey 
Receiver 


Alpha 


1 


arg5 


Msg ID 


Alpha 


4 


arg6 


Msg Iss. 


Alpha 


6 


arg7 


Msg Line 
Count 


Integer 


4 



arg8 Msg Text Alpha var 



Size Comments 

2 Type of request: 

I = Specify initial parameters 
R = Respecify parameter (s) (error cor- 
rection) 
ID = Satisfy initial parameters from 

defaults 
RD = Satisfy correction parameters 
from defaults 
See Note 1 for request type descriptions. 

1 Form of screen: 

A = Acknowledge 

R = Request 

S = Select 
Unless the program specifies a PF key mask 
(see PFKEY Mask Specification) with the 
Request and Acknowledge forms, all PF 
keys are disabled; with the Select form, all 
PF keys are enabled. See Note 1 for request 
form descriptions. 

Parameter reference name. To satisfy the 
request via Procedure language statements, 
prname must be alphanumeric. 

AID byte. For type ID or RD, indicates key 
that selects default option. If not used, initial- 
ize to @. See Table 3- 1 8 for AID bytes and 
their meanings. 

Identifies particular GETPARM screen. 

Identifies source of screen. 

Number of lines of message. The message 
can be specified either as individual lines of 
text (arg7 nonnegative), or as a single block 
(arg7 omitted). 

Message text. 

Arg 7 specified: arg8 is an individual line of 
text, and arg 8 and arg9 are repeated for 
each separate line of text in the message. 
Each line can begin with one or more of the 
following control characters: 

X'5E' (up-arrow) = Center msg text 
X'5F' (underscore) = Underline msg text 
X'2T (exclamation pt) = Blink msg text 
Arg 7 omitted: arg8 is the entire message 
text, where lines are separated by an 
X'OD' character. 
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Pos Argument Type Size Comments 

arg9 Msg Text Integer 4 Length of message text. A text length of 

Length 0, excluding control characters, causes no 

text line to be generated. If the argument 
list contains only empty text strings, a 
single blank is generated as the text. 



Keyword Field GETPARM Type 

The following argument list defines a single Keyword field, for which the user or Proce- 
dure language statements can supply the parameters. The entire set of arguments is 
specified once for each keyword. 



Pos Argument Type Size 

argl Type Alpha 1 



arg2 Keyword Alpha 8 



arg3 Value 



arg4 Length 



Alpha var 



Integer 4 



arg5 Row Flag Alpha 1 



arg6 Row 



Integer 4 



arg7 Col. Flag Alpha 1 



Comments 

Specifies keyword field type: 

K/k = Standard keyword field. 

R/r = Error-respecify keyword field. 
See Note 2 for uppercase and lowercase 
usage. 

Keyword name. Can contain any characters, 
but must be alphanumeric if Procedure lan- 
guage statements specify parameters. 

Initial value of keyword. Blanks in the field 
are converted to pseudoblanks on the 
screen and back to blanks after the user 
presses a PF key or the ENTER key. 

Length of keyword field. The user specifies 
zero to process entire field as skip specifica- 
tion (as though argl =k or r). 

Indicates how to position this field: 

A = Absolute. Rows 9-24 are available, 
but the row depends on how many 
lines of message text were dis- 
played. 
R = Relative (default). Calculated from 
the "current" row (most recent row 
displayed), or initial default. 
Optional. 

Row to display this field. 
Arg5=A: arg6 is actual row. 
Arg5=R. arg6 is number of rows from "cur- 
rent" row. If the user has not specified any 
fields, current row is (n+8) where n is the 
number of lines of message text specified 
(minimum of 1 ). 

Indicates how to position this field: 

A = Absolute (columns 2-80 are avail- 
able). 
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Pos Argument Type 



Size Comments 



arg8 Column 



Integer 4 



apg9 Data Type Alpha 1 



R = 



C = 

J = 



Relative (default). For a new row, 
"current" column is 2. (Can be 
0-78.) 

Center the field in the specified row. 
Right-justify the field in the speci- 
fied row. 



Optional. 

Column to display this field. 
Arg7—A: arg8 is column to display field. 
Arg7=R: arg8 is number of columns from 
"current" column. Current column is either 2 
(initially, or whenever a row value other than 
Relative is specified), or the end position 
of the last field specified plus 1 trailing blank. 
Arg7=CorJ: arg8 is optional, and is ignored 
if included. 

Data type for this field. 

Uppercase generates modifiable fields. 

Lowercase generates protected fields. 
A/a = Alphanumeric only (A-Z, 0-9, #, 
@, $). Letters converted to 
uppercase. 

Any character accepted. 
Unsigned integers only (0-9). 
Numeric only (optional decimal 
point and sign). 

Limited alphanumeric (A-Z, 0-9, 
#, @, &). Letters converted to 
uppercase. First character must 
not be a number. 

Any characters. Letters converted 
to uppercase. 

Hexadecimal digits only (0-9, 
A-F). Numeric and integer fields 
are limited to 1 6 characters in 
length. The VS Procedure lan- 
guage allows the user to override 
protected fields. 



C/c = 

l/i = 

N/n = 

L/I = 



U/u = 



H/h = 



Text Field GETPARM Type 

The Text Field type causes text to be displayed on the GETPARM screen. The program 
specifies the entire argument list once for each line of text to be displayed. 
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Pos Argument Type Size 

arg! Type Alpha 1 



arg2 


Text 


Alpha 


var 


arg3 


Length 


Integer 


4 


arg4 


Row Flag 


Alpha 


1 


arg 5 


Row 


Integer 


4 


arg6 


Col. Flag 


Alpha 


1 


arg 7 


Column 


Integer 


4 



Comments 

Specifies text field type: 
T/t = Text field 

U/u = Underlined text field See Note 2 
for upper and lowercase usage. 

Line of text to be displayed. 

Length of text line (arg2). Specify zero to 
cause the entire text field spec to be pro- 
cessed as a skip (as though argl =t or u). 

See arg 5 of Keyword field type. 

See arg 6 of Keyword field type. 

See arg 7 of Keyword field type. 

See arg 8 of Keyword field type. 



PF Key Mask Specification 

This specification type allows the program to enable/disable any of the 32 PF keys. 



Pos Argument Type 

arg 1 Type Alpha 



arg2 PF key Alpha 

mask 



Size Comments 

1 Specifies PF Key Mask specification type: 

P/p = PF Key Mask type 
See Note 2 for uppercase and lowercase 
usage. 

4 Four byte (32 bit) mask. Each bit corre- 

sponds to a PF key: leftmost bit to PF1 , 
rightmost bit to PF32. A bit value of 1 
enables the corresponding key, disables 
the key. For example, the user enables all 
keys by specifying the value X'FFFFFFFF'. If 
no mask is supplied, the default action is to 
disable all PF keys for Acknowledge and 
Request forms, and to enable all PF keys for 
the Select form. 



ENTER Flag Specification 

This specification type allows the user to enable/disable the ENTER key. The default for 
all form types is to enable the ENTER key. 

Pos Argument Type Size Comments 

argl Type Alpha 1 Indicates ENTER Flag specification type: 

E/e = Enable ENTER key 
N/n = Disable ENTER key 
See Note 2 for upper and lowercase usage. 



GETPARM-5 



NOTES 

1 . The GETPARM request types are 2-byte values, constructed as follows: 

Byte 1 = I, generates an "initial" request, which can be satisfied by a procedure. 
Byte 1 = R, generates a "respecification" (correction) request, which cannot be 
satisfied by a procedure. 

Byte 2 = blank, the subroutine satisfies the request via the workstation. Byte 2 = 
D, the subroutine satisfies the request via current ("default") values for the key- 
words that comprise the request. 

Thus, the combinations work as follows: 

Type = "I ": the subroutine searches for a procedure to satisfy the requested 
parameters. If they are not found in a procedure, it requests input from the work- 
station. 

Type = "ID": the subroutine searches for a procedure to satisfy the requested 
parameters. If none, it uses current values and continues without displaying the 
request on the workstation. 

Type = "R ": the subroutine satisfies the request from a workstation display. 

Type = "RD": the subroutine satisfies the request from current values only. (This 
type is not very useful.) 

The following table lists the screen heading that is displayed for each request type 
and form if workstation input is required. 

Heading 

RESPONSE REQUIRED BY PROGRAM name 

TO ACKNOWLEDGE prname 
INFORMATION REQUIRED BY PROGRAM name 

TO DEFINE prname 
RESPONSE REQUIRED BY PROGRAM name 

TO SELECT prname 
CORRECTION REQUIRED BY PROGRAM name 

TO ACKNOWLEDGE prname 
CORRECTION REQUIRED BY PROGRAM name 

TO DEFINE prname 
CORRECTION REQUIRED BY PROGRAM name 

TO SELECT prname 

2. Uppercase values cause the field, PF mask, or ENTER flag to be displayed or 
executed. Lowercase values cause the sequence of arguments of which this argu- 
ment is a part to be skipped or ignored. Skip specifications allow a program to 
select particular parameters at runtime without having to generate several similar 
CALL statements. 

3. FORTRAN programs must specify the name of this subroutine as GETPRM. 



Type 


Form 


I 


A 


I 


R 


I 


S 


R 


A 


R 


R 


R 


S 



GETPARM-6 



GETPARM Subroutine - A BASIC Example 



This program first displays a screen that requests that the user provide the GETPARM type, form, 
prname, and the message number, ID, and up to 2 lines of message text. When the user presses the 
ENTER key, the program displays a GETPARM screen that includes the user-supplied information. It 
also demonstrates the use of a variety of fields, including alphanumeric, blinking, uppercase, integer, 
numeric, and protected. The program disables all but PF5. 

000100DIM TYPES 02 

000200DIM FORMS 01 

000300DIM PRNAMES 08 

000400DIM PFKEYRECEIVERS 1 

000500DIM MESSAGENOS 04 

000600DIM MESSAGEIDS 06 

000700DIM MESSAGElS 60 

000800DIM MESSAGE2$ 60 

000900TYPE$ = "I " 

001000FORM$ = "S" 

001100DIM A$121 

001200AGAIN: 

001300GOSUB FORMATSCREEN 

001400GOSUB DOGETPARM 

001500GOTO AGAIN 

001600 

001700DOGETPARM: 

001800A$ = MESSAGElS & HEX(OD) & MESSAGE2$ 

001900CALL "GETPARM" ADDR (TYPES, FORMS , PRNAME$ , 

002000 

002100 

002200 

002300 

002400 

002500 

002600 

002700 

002800 

002900 

003000 

003100 

003200 

003300 

003400 

003500 

003600 

003700RETURN 



PFKEYRECEIVERS, MESSAGENOS, MESSAGEIDS, 
A$,121%, 



"N" 
< ■ p > ■ 

"T" 
"K" 

"R" 

"K" 

"K" 
"K" 
"T" 
"K" 

"T" 



HEX(FFFF), 

"This is a TEXT FIELD. ", 21%, 1%, 0%, 
"ALPHANUM" , "THISALPHANUMERICFIELDHASNOBLKS" ,30% 

,2%, 15%, "A" , 
"BLINK " , "This field blinks, allows all characters. 

,44%,1%,0%, "C" , 
"UPPER "."This is an UPPERCASE FIELD'. " ,27%, 1% 

,0% , " U " , 
"INTEGER " , "7777788888999996" ,16%, IX, OX, "I" , 
"NUMERIC " , "1234567890.09876" ,24%, IX, OX, "N" , 
"SPECIAL PROTECTED OPTION ! ! 11 " , 28%, 3%, 15%, 
"CHARPROT" , "This is a CHARACTER PROTECTED FIELD." 

,36%,1%,0%, "c" , 
"ENTER is disabled; only PF5 works . " , 34%, 2%, 0%) 
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003800 

003900FORMATSCREEN: 

004000ACCEPT 

004100 AT (01,24), 

004200"Demonstration of GETPARM Subroutine", 

004300 AT (06,04) , 

004400"Specify the following parameters, and press ENTER to get a GETPA 

004500RM screen. ' ' , 

004600 AT (08,03), 

004700"TYPE: " , 

004800 AT (08,14), TYPES , CH(02), 

004900 AT (08,18), 

005000" (I-initial; R-respecify; ID-initial dflt; RD-respecify dflt)", 

005100 AT (09,03), 

005200"FORM: " , 

005300 AT (09,14), FORMS , CH(01), 

005400 AT (09,18), 

005500" (R-request; S-select; A-acknowledge) " , 

005600 AT (10,03), 

005700 "PRNAME: " , 

005800 AT (10,14), PRNAMES , CH(06), 

005900 AT (11,03), 

006000"MESSAGE #: " , 

006100 AT (11,14), MESSAGENOS , CH(04), 

006200 AT (12,03), 

006300"MESSAGEID: " , 

006400 AT (12,14), MESSAGEID$ , CH(06), 

006500 AT (13,03), 

006600"MESSAGE: " , 

006700 AT (13,14), MESSAGE1$ , CH(60), 

006800 AT (14,14), MESSAGE2$ , CH(60), 

006900 AT (18,03), 

007000"Press ENTER, look at the GETPARM, and see where your parameters 

007100were placed. " 

007200RETURN 
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GETPARM Subroutine - A COBOL Example 



This oroqram creates a GETPARM screen that allows the user to specify an output file. The 
GETPAraKfor initial parameters and has the request form. Fields for the file, l.brary, and volume 
names, with a prompt centered and blinking above them, appear on the screen. 



000100 

000200 

000300 

000400 

000500 

000600 

000700 

000800 

000900 

001000 

001100 

001200 

001300 

001400 

001500 

001600 

001700 

001800 

001900 

002000 

002100 

002200 

002300 

002400 

002500 

002600 

002700 

002800 

002900 

003000 

003100 

003200 

003300 

003400 

003500 

003600 

003700 

003800 

003900 

004000 

004100 

004200 

004300 

004400 



CONTROL CHARACTERS FOR THE 



IDENTIFICATION DIVISION. 
PROGRAM-ID. GETPARMC. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
FIGURATIVE-CONSTANTS. 
•THE TWO USER-FIGURATIVE-CONSTANTS ARE 
*GETPARM MESSAGE. 

CENTER IS "5E" 

BLINK IS "21" . 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
77 TY-PE PIC X(2) VALUE "I". 

FO-RM PIC X VALUE "R" . 

PR-NAME PIC X(8) VALUE "OUTPUT". 

KEY-RECEIVER PIC X(l). 

MESSAGE-NUMBER PIC X(4) VALUE "9999". 

MESS-ENGER PIC X(6) VALUE "GETPAR". T1 -„ rnP 

EXPLAINED IN SECTION 2.2.2, COBOL ACCEPTS HALFWORD INTEGERS 



77 
77 
77 
77 
77 
AS 



COMPOSED OF TWO 
THE LOW-ORDER TWO 
TO THE SUBROUTINE, 



•ONLY DEFINE A FOUR-BYTE GROUP ITEM TO BE 
•HALFWORD-BINARY, ELEMENTARY ITEMS, AND USE 
•BYTES FOR THE INTEGER. TO PASS AN INTEGER 
•INITIALIZE THE HIGH-ORDER BYTES TO ZERO. 
01 LINE-COUNT. 

03 FILLER USAGE IS BINARY VALUE 0. 

03 LINE-OFFSET USAGE IS BINARY VALUE 1. 

MESS-AGE. 

03 CONTROL-1 PIC X VALUE CENTER. 

03 CONTROL-2 PIC X VALUE BLINK. 

03 TEXT PIC X(27) VALUE "PLEASE SUPPLY THESE VALUES 

MESSAGE-LENGTH. 

03 FILLER USAGE IS BINARY VALUE 0. 

03 M-LENGTH USAGE IS BINARY VALUE 29. 

KEYWORD-TYPE PIC X VALUE "K". 

KEYWORD-1 PIC X(8) VALUE "FILE". 

VALUE-1 PIC X(8) VALUE SPACES. 

VALUE-LENGTH. 

03 FILLER USAGE BINARY VALUE 0. 

03 LENGTH USAGE BINARY VALUE 8. 

ROW-1. 

03 FILLER USAGE IS BINARY VALUE 0. 

03 ROW-VALUE-1 USAGE IS BINARY VALUE 1. 

COL-UMN. 

03 FILLER USAGE IS BINARY VALUE 0. 

03 COLUMN-VALUE USAGE IS BINARY VALUE 10. 



01 



01 



77 
77 
77 
01 



01 



01 
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004500 

004600 

004700 

004800 

004900 

005000 

005100 

005200 

005300 

005400 

005500 

005600 

005700 

005800 

005900 

006000 

006100 

006200 

006300 

006400 

006500 

006600 

006700 

006800 

006900- 

007000 



77 
77 
01 



01 



77 DATA-TYPE PIC X(2) VALUE "L". 

77 KEYW0RD-2 PIC X(8) VALUE "LIBRARY" 

77 VALUE-2 PIC X(8) VALUE SPACES. 

01 ROW-2. 

03 FILLER USAGE IS BINARY VALUE 0. 
03 R0W-VALUE-2 USAGE IS BINARY VALUE 5 
KEYW0RD-3 PIC X(6) VALUE "VOLUME" 
VALUE-3 PIC X(6) VALUE SPACES. 
VALUE-3-LENGTH. 

03 FILLER USAGE IS BINARY VALUE 0. 
03 VOLUME-LENGTH USAGE IS BINARY VALUE 
ROW-3. 

03 FILLER USAGE IS BINARY VALUE 0. 
03 ROW-VALUE-3 USAGE IS BINARY VALUE 
PROCEDURE DIVISION. 
MAIN-PARAGRAPH. 

CALL "GETPARM" USING TY-PE, FO-RM 
MESSAGE-NUMBER, MESS-ENGER, LINE- 
MESSAGE-LENGTH, KEYWORD-TYPE, KEYWORD-1 
VALUE-LENGTH, ROW-1, COL-UMN, DATA-TYPE ' 
KEYWORD-TYPE, KEYWORD-2, VALUE-2, VALUE-LENGTH ROW-2 
COL-UMN, DATA-TYPE, KEYWORD-TYPE, KEYWORD-3, VALUE-3 
VALUE-3-LENGTH, ROW-3, COL-UMN, DATA-TYPE 
DISPLAY "VALUE-1 = "VALUE-1, " VALUE-2 = "VALUE-2 " VALUE-3 

" = "VALUE-3. 
STOP RUN. 



4. 



PR-NAME, KEY-RECEIVER, 
-COUNT, MESS-AGE, 
VALUE-1, 
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GETPARM Subroutine — A FORTRAN Example 

This program displays a screen that prompts the user to select the GETPARM type and form the 
pmam ? and message information and text. When the user presses ENTER, the program d.splays a 
GEtTaRM screen with the user-specified information. Text fields demonstrate the use of various 
fields, including alphanumeric, blinking, forced uppercase, integer, numeric, and protected. The pro- 
gram disables all but PF5. 

L0GICAL*1 FORM, LINEK40), LINE2U0), PFK, PFREC 

INTEGERS TYPE 

REAL*8 PRNAME, MISS 

DATA LINE1/40H DEMONSTRATION OF THE GETPARM SUBROUTINE/, 

1 LINE2/40H I-TYPE, ACKNOWLEDGE FORM /, 

2 PFK PVALUE/'P' .ZFFFF0000/, PRNAME/ 'GPFOR '/, 

3 TYPE, FORM, MID, MISS/'I ' , ' S ' , ' 0001 ' , 'GPF0R1' / 
C SET VALUES FOR GETPARM DEFINITION ARGUMENTS 

CALL GTPARM CI ', 'S ', PRNAME , PFREC ,' 0001 ',' GPFOR ',2, 

1 ' SPECIFY THE FOLLOWING PARAMETERS ', 33 , 

2 ' THEN PRESS ENTER TO GET A GETPARM SCREEN', 41, 

3 'K\'TYPE '.TYPE ,2, 1,0, 'A', 

4 'K'.'FORM '.FORM ,1,1,0, 'A', 

5 'K',' PRNAME ' , PRNAME , 6 , 1 , , ' A' , 

6 'K'.'MSG ID ' ,MID ,4,1,0,'C, 

7 'K'.'MSG ISS ' ,MISS ,6,1.0, 'C, 

8 'K'.'LINEl ' ,LINE1,40,1,0,'C\ 

9 *K','LINE2 \LINE2,40,1,0,'C') 

CALL GTPARM (TYPE , FORM, PRNAME , PFREC, MID , MISS , 2 , 

1 LINE1.40.LINE2.40, 

2 'N', 

3 PFK, PVALUE, 

4 'K\'ALPHANUM','LETTERSONLY',11,1,0,'U', 

5 'R' 'BLINK ','A11 characters BLINKING' ,23 ,1,0 , 'C , 

6 'K'''UPPER ' .'UPPERCASE FIELD' ,15, 1,0, 'U' , 

7 «K\ 'INTEGER ', '12345678' ,8,1,0, T , 

8 'K', 'NUMERIC ' , ' 12345 .78' , 8, 1, , 'N' , 

9 'T' 'SPECIAL PROTECTED OPTION!' ,25,3,15, 

1 'K'''CHARPROT','Char. PROTECTED FIELD' ,21,1.0, 'C , 

2 't', 'enter disabled, only pf5 works ' , 30 , 2 , 0) 
pause' 

END 
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GETPARM Subroutine - AIM RPG II Example 

This program creates the GETPARM screen shown below and displays a screen acknowledqinq the 
user s input a a 



!■##»## i 



* * # » * 



* # * MESSAGE 001 BY TEST1 

RESPONSE REQUIRED BY PROGRAM TEST 
TO SELECT OPTIONS 

ENTER FILE INFORMATION AND PRESS PF5 TO DEFINE INPUT, OR 

PRESS PF16 TO END JOB. 



FILE 

LIBRARY 

VOLUME 



* # • # * 



■####■*#* 



■«*#**♦« 



####». 



*###»*###i 



■*»#»##♦, 



>####*###< 



00100FDISPLAY DD F 



00100C* 

00150C* 

00200C 

00300C 

00400C 

00500C 

00600C 

00700C 

00702C* 

00704C* 

00706C* 

00710C 

00720C 

00730C 

00740C 

00750C 

00760C 

00770C 

00780C 

00790C 

00791C 



WS 

PREPARE PARAMETERS TO PASS TO RPGCALL MACRO 

MOVE 'I ' TYPE 2 

MOVE 'S' FORM 

MOVE 'OPTIONS 'PRNAME 8 

MOVE ' ' PFK 1 

MOVE '001 ' MSGID 4 

MOVE 'TEST1 ' MSGIS 6 



USE TEMPORARY VARIABLES TO BUILD MESSAGE LONGER THAN 8 BYTES 



MOVEL'ENTER FI ' 
MOVE 'LE INFOR' 
MOVEL'MATION A' 
MOVE 'ND PRESS' 
MOVELTEMP1 
MOVE TEMP2 
MOVEL' PF5 TO ' 
MOVE 'DEFINE I' 
MOVEL 'NPUT, OR' 
MOVELTEMP1 



TEMPI 


16 


TEMPI 




TEMP2 


16 


TEMP2 




HOLD1 


32 


H0LD1 




TEMPI 




TEMPI 




TEMP3 


8 


HOLD2 


24 
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00792C 

00793C 

00794C 

00900C 

9-1000C 

02000C 

02100C 

02200C 

02300C 

02400C 

02900C 

03000C 

03100C 

03200C 

03300C 

03400C 

03500C 

03600C 

03700C 

03800C 

03810C 

03900C 

04000C 

04100C 

04200C 

04300C 

04400C 

04410C 

04500C 

04600C 

04700C 

04800C 

04900C 

05000C 

05100C 

05102C* 

05104C* 

05105C* 

05106C 

05110C 

05120C 

05121C 

05122C 

05123C 

05124C 

05130C 

05140C 

05150C 

05155C 

05160C 

05165C 



MOVE TEMP3 
MOVELHOLD1 
MOVE H0LD2 
Z-ADD56 
MOVE 'T' 
MOVEL' PRESS PF 
MOVE '16 TO EN 
MOVE 'D JOB. 
MOVELTEMP1 
MOVE TEMP3 
Z-ADD24 
Z-ADDO 
Z-ADDO 
MOVE 'K' 
MOVE 'FILE 
MOVE ' ' 
Z-ADD8 

Z-ADD3 

Z-ADD5 

MOVE 'A' 

MOVE 'K' 

MOVE 'LIBRARY 

MOVE ' ' 

Z-ADD8 

Z-ADD1 

Z-ADD5 

MOVE 'A' 

MOVE 'K' 

MOVE 'VOLUME 

MOVE ' ' 

Z-ADD6 

Z-ADD1 

Z-ADD5 

MOVE 'A' 

MOVE 'P' 



56 



H0LD2 
MSG 
MSG 

MSGLN 40 
T 1 
'TEMPI 
'TEMPI 
'TEMP3 
TEXT 24 
TEXT 

TEXTLN 40 
ROWSK 40 
COLSK 40 
Kl 

'KEY1 
VAL1 
LEN1 
R0WSK1 40 
C0LSK1 40 



1 

8 

8 

40 



TYPE1 
K2 

'KEY2 
VAL2 
LEN2 
R0WSK2 40 
C0LSK2 40 



1 
1 
8 
8 
40 



TYPE2 
K3 

'KEY3 
VAL3 
LEN3 
R0WSK3 40 
C0LSK3 40 
TYPE3 1 
P 1 



1 
1 
8 
6 
40 



PREPARE PF KEY MASK USING BITON AND BITOF 
*** (ENABLE PF 5 AND 16 ONLY) *** 



BITON' 4' 


PM1 


1 


BITOF'0123567' 


PM1 




BIT0N'7' 


PM2 


1 


BITOF'0123456" 


PM2 




BITOF'01234567 


'PM3 


1 


BITOF'01234567 


'PM4 


1 


M0VELPM1 


PM5 


2 


MOVE PM2 


PM5 




M0VELPM3 


PM6 


2 


MOVE PM4 


PM6 




M0VELPM5 


PMASK 


4 


MOVE PM6 


PMASK 
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05170C* 

05175C* 

05180C* 

05300C 

05310C* 

05320C* 

0530C* 

05400C 

05500C 

05600C 

05700C 

05800C 

05900C 

06000C 

06100C 

06200C 

06300C 

06400C 

06500C 

06600C 

06700C 

06800C 

06810C 

06820C 

06900C 

07000C 

07100C 

07200C 

07300C 

07400C 

07500C 

07600C 

07700C 

07800C 

07900C 

08000C 

08100C 

08200C 

08300C 

08400C 

08500C 

08600C 

08700C 

08710C 

08720C 

08722C* 

08724C* 

08725C* 

08727C* 

08730C 

08820C 

08830C 



PMASK IS THE PF KEY MASK; EFLAG IS THE ENTER FLAG * 
MOVE 'N' EFLAG 1 
*** EXIT TO RPGCALL MACRO *** 



EXIT RPGGET 




RLABL 


TYPE 


RLABL 


FORM 


RLABL 


PRNAME 


RLABL 


PFK 


RLABL 


MSGID 


RLABL 


MSGIS 


RLABL 


MSG 


RLABL 


MSGLN 


RLABL 


T 


RLABL 


TEXT 


RLABL 


TEXTLN 


RLABL 


ROWSK 


RLABL 


COLSK 


RLABL 


Kl 


RLABL 


K2 


RLABL 


K3 


RLABL 


KEY1 


RLABL 


KEY2 


RLABL 


KEY3 


RLABL 


VAL1 


RLABL 


VAL2 


RLABL 


VAL3 


RLABL 


LEN1 


RLABL 


LEN2 


RLABL 


LEN3 


RLABL 


ROWSK1 


RLABL 


ROWSK2 


RLABL 


R0WSK3 


RLABL 


COLSK1 


RLABL 


COLSK2 


RLABL 


C0LSK3 


RLABL 


TYPE1 


RLABL 


TYPE2 


RLABL 


TYPE3 


RLABL 


P 


RLABL 


PMASK 


RLABL 


EFLAG 



IF PF 16 WAS PRESSED, END JOB; OTHERWISE, ACKNOWLEDGE 
*** USER'S INPUT *** 



PFK 



N99 



COMP 'P' 

ACCPTSCR1 

SETON 



99 



LR 
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08920WSCR1 

09020W 

09120W 

09220W 

09320W 

09420W 

09520W 

09620W 



0707 


'INPUT FILE IS' 




0721VAL1 
0807 


'IN LIBRARY' 




0821VAL2 
0907 




'ON VOLUME' 


0921VAL3 
1205 




'PRESS ENTER TO END JOB 



RPGGET: 



RPGCALL NAME=RPGGET, CALL=GETPARM, TYPE, FORM, PRNAME.PFK, 
MSGID.MSGIS.MSG, (MSGLN,4,F) ,T,TEXT, (TEXTLN.4.F) , 
(R0WSK P 4,F),(C0LSK,4,F),K1,KEY1,VAL1,(LEN1,4,F), 
(R0WSK1,4,F),(C0LSK1,4,F),TYPE1,K2,KEY2 > VAL2,(LEN2,4,F) 
(R0WSK2 , 4 , F ) , (C0LSK2 , 4 , F) , TYPE2 , K3 , KEY3 , VAL3 , ( LEN3 , 4 , F ) 
(R0WSK3,4,F) , (C0LSK3,4,F) , TYPE3 , P, PMASK, EFLAG 
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HEX PACK 

FUNCTION 

Converts a string of hexadecimal digits to its ASCII character equivalent. 



USAGE (argl arg3) 

Pos Argument Type 

argl Hex Alpha 

digits 

arg2 Receiver 



arg3 Length 



Size Comments 

var String of hexadecimal digits to be converted. 

var String to receive the ASCII characters. The 

length of this string must be at least half the 
length of the input string. 

Integer 4 Length of input string. If odd, the program 

ignores the last character of the input string. 



Alpha 



NOTES 

1 . This subroutine is equivalent to the BASIC language HEXPACK statement. 

2. The subroutine does not check for valid hexadecimal digits. 

3. For FORTRAN programs, the name of this subroutine must be specified as 
HXPACK. 
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HEXPACK Subroutine - A FORTRAN Example 

This example converts a user-supplied hexadecimal character string into its ASCII equivalent. Both 
are displayed on the screen. 

LENGTH = 4 

WRITE(O.lOl) ' ENTER 4 HEX CHARS' 
C 'HCHARS' CONTAINS 4 HEXADECIMAL CHARACTERS TO BE CONVERTED 

READ(0,102) HCHARS 
C STOP IF USER ENTERS 9999 

IF (HCHARS. EQ. '9999') GO TO 99 
C 

C 'ACHARS' CONTAINS THE ASCII STRING THAT CORRESPONDS TO HCHARS 
C CALL HEXPACK (HXPACK IN FORTRAN) TO PERFORM THE CONVERSION 

CALL HXPACK (HCHARS, ACHARS, LENGTH) 
C 

WRITE(0,103) HCHARS, ACHARS 

101 FORMAT (A20) 

102 FORMAT (A4) 

103 F0RMAT(1X, Z8, 5X, A2) 
99 PAUSE 

END 
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HEXUNPK 

FUNCTION 

Converts a string of ASCII characters into hexadecimal digits. 



USAGE (argl arg3) 

Pos Argument Type 



argl 
arg2 



ASCII st. 
Receiver 



arg3 Length 



Alpha 
Alpha 

Integer 



Size Comments 

var String of ASCII characters to be converted. 

var String to receive the hexadecimal characters. 

The length of this string must be at least 
twice the length of arg 1 . 

4 Length of the input string. 



NOTES 

1 . This subroutine is equivalent to the BASIC language HEXUNPACK statement. 

2. For FORTRAN programs, the name of this subroutine must be specified as 
HXUNPK. 
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HEXUNPK Subroutine - A FORTRAN Example 

This example converts an ASCII string entered by the user into its hexadecimal equivalent. Both are 
displayed on the screen. 

C 'ALPHA' CONTAINS UP TO 5 ASCII CHARACTERS 
C 'HEX' IS ITS HEXADECIMAL EQUIVALENT 

LOGICAL'l ALPHA(5), HEX(IO) 

WRITE(0,101) ' ENTER LENGTH, STRING' 

READ(0,102) LENGTH, (ALPHA(I), 1=1, LENGTH) 
C USER ENTERS * TO STOP 

IF(ALPHA(1) .EQ. 1H*) GO TO 99 
C 
C CALL HEXUNPK (HXUNPK IN FORTRAN) TO PERFORM CONVERSION 

CALL HXUNPK(ALPHA, HEX, LENGTH) 
C 

WRITE(0,103) HEX 

101 FORMAT(A21) 

102 FORMAT (II, 5A1) 

103 FORMAT (IX, 10A1) 
99 PAUSE 

END 
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LINK 



FUNCTION 

Allows the user to link to a program or procedure and to specify a cancel exit for the 
link. The user program can also specify any arguments that are needed to execute the 
linked program or procedure. 



USAGE (arg1,... r arg15) 
Pos Argument Type 



argl 
arg2 



Program 
Link Type 



arg6 Arg(s) 



arg7 Cancel 
Exit Flag 



Size Comments 



Alpha 
Alpha 



arg3 Library 



arg4 Volume 



arg5 Argument Integer 4 
Count 



Variable 



arg8 Message Alpha var 



arg9 Message 
Length 

arg10 HELP Dis- 
able Flag 



8 Program or procedure to be linked to. 

1 Where program to be linked resides: 

S = Check system only 
P = Use library/volume named in arg3 

and arg4 
Blank = Use program library and volume 
associated with the user 

Alpha 8 Library (must be included, but is ignored 

unless arg2=P). 

Alpha 6 Volume (must be included, but is ignored 

unless arg2=P). 

Number of arguments to be passed to the 
program. See arg6. This value can be 0. 

Arguments) to be passed to the linked pro- 
gram. Arg5 specifies the number of times 
this argument is repeated. If arg5=0, this 
argument must be omitted. The length and 
type of this argument depend on the require- 
ments of the linked program. 

Cancel exit option: 

C = Cancel exit only 

N = Cancel exit, allow no debug process- 
ing 

D = Cancel exit, allow no debug process- 
ing but generate full dump 

Blank = No special exit processing 

Message to override PF1 6 text. Ignored if 
arg7 is blank. Maximum length is 27 charac- 
ters. 

Integer 4 Length of PF1 6 message (arg8). 

Specify zero for no PF1 6 message override. 

Alpha 1 HELP key disable/enable: 

N = Disable HELP 
H or blank = Enable HELP 



Alpha 



LINK-1 



Pos Argument Type Size 

Alpha 2 



arg11 PFKey 
Mask 



arg 1 2 Cancel 
Receiver 

arg 13 Cancel 
Receiver 
Length 



Alpha var 
Integer 4 



arg 14 Completion Integer 4 
Code 



arg 15 Ret. Code Integer 4 



Comments 

32-bit mask to enable/disable Command 
Processor PF keys. This feature is not cur- 
rently implemented in the operating system. 

Receiver for the cancel exit information list. 
Ignored if arg7 is blank. 

Maximum length of argl 2. Must be nonzero. 
Register and other information require 1 28 
bytes; the remainder of argl 2 contains as 
much of the cancel message list as fits into 
the value of arg 1 3 minus 1 28. 

Indicates the result of the link: 
= Successful link 
8 = Unsuccessful link 
16 = Program canceled 

Error return code. 

Arg 14=0: This is the return code from the 

linked program. 

Arg 14=8: See Table 3-5 below. 

Argl 4= 16: This field is not set. 



NOTE 

Arguments 2 and 5 through 1 3 are optional; however, if any of them is included, all 
preceding arguments must be present. Several arguments must be present in pairs, 
whether or not both are used (args 8 and 9, and args 1 2 and 1 3). If arg5 is zero, arg6 
must be omitted, and arguments 1 4 and 1 5 are both required. 



Table 3-5. LINK Error Return Codes 



Return 




Code 


Meaning 



4 


Not a program file, and the procedure interpreter cannot be invoked. 
Volume not mounted. 


8 
12 
16 
20 
24 


Volume in exclusive use by another user. 
All buffers in use when one was required. 
Directory not found. 
File not found. 
(Unused). 


28 
32 
36 
40 
44 


Access to program's file-protection class denied. 

FDX1 and FDX2 conflict detected by READFDR. 

FDX2 and FDR conflict detected by READFDR. 

Invalid parameter passed to READFDR (including NL volume type) 

I/O error on VTOC. 


48 
52 
56 


Unable to read FDR2 record (additional extent specifications). 
Invalid program file; unable to complete link. 
File open other than shared read-only. 
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LINK Subroutine — A COBOL Example 



This program links to the EDITOR dynamically. It also specifies an exit option that returns to the pro- 
gram rather than to the Command Processor if the linked-to program is cancelled. 



000100 

000200 

000300 

000400 

000500 

000600 

000700 

000800' 

000900' 

001000 

001100 

001200' 

001300' 

001400' 

001500' 

001600' 

001700 

001800 

001900 

002000 

002100 

002200 

002300 

002400 

002500 

002600 

002700 

002800 

002900 

003000 

003100 

003200 

003300 

003400 

003500 

003600 

003700 

003800 

003900 



TWO ARGUMENTS ARE IGNORED 



IDENTIFICATION DIVISION. 

PROGRAM-ID. LINKC. 

ENVIRONMENT DIVISION. 

DATA DIVISION. 

WORKING-STORAGE SECTION. 

77 LINKNAME PIC X(8) VALUE "EDITOR". 

77 LOCATION PIC X(l) VALUE "S". 

SINCE THE LINK TYPE IS "S", THE NEXT 

THOUGH THEY MUST BE CODED. 

77 LIB-RARY PIC X(8) . 

77 VOL-UME PIC X(6) . 

AS EXPLAINED IN SECTION 2.2.2, COBOL ACCEPTS HALFW0RD INTEGERS 

ONLY. DEFINE A FOUR-BYTE GROUP ITEM TO BE COMPOSED OF TWO 

HALFWORD-BINARY, ELEMENTARY ITEMS, AND USE THE LOW-ORDER TWO 

BYTES FOR THE INTEGER. TO PASS AN INTEGER TO THE SUBROUTINE, 

INITIALIZE THE HIGH-ORDER BYTES TO ZERO. 

01 PARAMETERS. 

03 FILLER USAGE IS BINARY VALUE 0. 

03 PARAMETER-COUNT USAGE IS BINARY VALUE 0. 

EXIT-OPTION PIC X VALUE "C". 

PF16-MESSAGE PIC X(16) VALUE "RETURN TO LINKC!". 

MESSAGE-LENGTH. 

03 FILLER BINARY VALUE 0. 

03 FILLER BINARY VALUE 16. 

COMPLETION. 

03 FILLER USAGE BINARY VALUE ZERO. 

03 COMPLETION-CODE USAGE BINARY. 

ERRORS. 

03 FILLER USAGE BINARY VALUE ZERO. 

03 ERROR-CODE USAGE BINARY VALUE ZERO. 
PROCEDURE DIVISION. 
MAIN-PARAGRAPH. 

CALL "LINK" USING LINKNAME, LOCATION, 
PARAMETERS, EXIT-OPTION, 
PF16-MESSAGE, MESSAGE-LENGTH, 
COMPLETION, ERRORS. 

DISPLAY "THE COMPLETION CODE IS "COMPLETION-CODE, 
" THE RETURN CODE IS "ERROR-CODE. 

STOP RUN. 



77 
77 
01 



01 



01 



LIB-RARY, VOL-UME, 
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LINK Subroutine - AN RPG II Example 



This program allows the user to update the records of File A or to run the SORT utility. When the 
user presses PF1 from Screen 1 (SCR1), the program calls LINK and links to the SORT utility. If the 
user interrupts SORT with the HELP key, the cancel exit message supplied here ("RESUME 
UPDATING FILE A") replaces the usual Command Processor PF1 6 message. The program checks the 
return code and the completion code and displays them if they are nonzero. 



00100FFILEA UC F 
00200FDISPLAY DD F 



09R04AI 



1 DISK 
WS 



00400IFILEA 

005001 

006001 



AA 01 



1 40KEYA 
5 9 INFOA 



00610C* 

00620C* 

00630C* 

00700C 

00800C 

00900C 

00910C 

00920C* 

00930C* 

00940C* 

00950C* 

01000C 

01010C 

01020C 

01100C 

01110C* 

01120C* 

01130C* 

01200C 

01300C 

01400C 

01500C 

01510C* 

01520C* 

01530C* 

01600C 

01720C 

01800C 

01900C 

01910C 

01920C 

01930C 

02000C 

02005C 

02010C 

02015C 



*** DISPLAY MENU 

MENU TAG 

ENBLEK0.KG.K1 

ACCPTSCR1 

SET0F 



99 



END JOB OR GO TO WHERE LINK IS PERFORMED OR 
"•• READ IN A RECORD TO UPDATE *** 



KG 
KG 

Kl 



LR 



K0 



SETON 
GOTO END 
GOTO SORT 
KEYA CHAINFILEA 

*** DISPLAY AND UPDATE RECORD 



ENBLEK0.K1 
ACCPTSCR2 
EXCPT 
GOTO MENU 

■• PREPARE PARAMETERS FOR LINK TO SORT UTILITY 



SORT 



TAG 






MOVE 'SORT 


'PROG 


8 


MOVE 'S' 


TYPE 


1 


MOVE 'DUMMY 


'LIBR 


8 


MOVE 'DUMMY 


'V0LM 


6 


Z-ADD0 


PCNT 


40 


MOVE 'C 


CEXT 


1 


MOVEL'RESUME U 


'DUM 


16 


MOVE 'PDATING 


'DUM 




MOVELDUM 


MSG 


22 


MOVE 'FILE A' 


MSG 
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02040C 

02050C 

02055C 

02060C* 

020650* 

02070C* 

02100C 

02200C 

02210C 

02300C 

02400C 

02500C 

02600C 

02700C 

02710C 

02711C 

02800C 

02801C* 

02802C* 

02803C* 

02810C 

02900C 

03000C 

03110C 

032000FILEA E 

033000 

034000 



Z-ADD22 


MSGLN 


40 


Z-ADDO 


CCODE 


40 


Z-ADDO 


RCODE 


40 



EXIT TO RPGCALL MACRO * 



EXIT RPGLNK 


RLABL 


PROG 


RLABL 


TYPE 


RLABL 


LIBR 


RLABL 


VOLM 


RLABL 


PCNT 


RLABL 


CEXT 


RLABL 


MSG 


RLABL 


MSGLN 


RLABL 


CCODE 


RLABL 


RCODE 



CHECK RETURN CODES 



03700WSCR1 

03720W 

03730W 

03740W 

03750W 

03760W 

03800W 

03900W 

04000W 

04100W 

04110W 

04120W 

04200W 

04300W 

04500WSCR2 

04600W 

04700W 

04800W 

04900W 

05000W 

05100W 



99 
99 
99 
99 
99 



CCODE COMP 


99 


RCODE COMP 


99 


GOTO MENU 


END TAG 




KEYA 


4 


INFOA 9 


B0107 


'ERROR IN SORT REQUEST' 


B0215 


'RETURN CODE = ' 


B0315 


'COMPLETION CODE = ' 


B0930RCODE 




B1035CC0DE 




0507 


'ENTER THE NUMBER OF TH' 


0529 


'E RECORD YOU WISH TO U' 


0551 


'PDATE, ' 


1015 




1207 


'OR PRESS PF 1 TO RUN T' 


1229 


'HE SORT UTILITY, ' 


1607 


'OR PRESS PF 16 TO END ' 


1629 


'THE JOB. ' 


0507 


'MAKE CHANGES AND PRESS' 


0530 


'ENTER TO UPDATE THIS R' 


0552 


'ECORD, ' 


0707 


'OR PRESS PF 1 TO EXIT. ' 


1215KEYA 




1315INF0A 





KEYA 40 



INFOA 



RPGLNK: 



RPGCALL NAME=RPGLNK,CALL=LINK, PROG, TYPE, LIBR.VOLM, C 
(PCNT, 4, F) , CEXT, MSG, (MSGLN, 4, F), (CCODE, 4 , F) , (RCODE , 4 , F) 
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LOADCODE 

FUNCTION 

Allows the user to load specified microcode into a device. 



USAGE (argl arg14) 

Pos Argument Type Size 

argl Function Alpha 1 



arg2 

arg3 
arg4 



TC Line 
Name 

Device Nr. 

Load Type 



Alpha 



arg7 Library Alpha 

Name 



arg10 Code 
Length 



arg 1 2 Renew 
Option 



Integer 



8 



Integer 4 
Alpha 1 



arg5 Microcode Integer 4 
Type 

arg6 Filename Alpha 8 



8 



arg8 Volume Alpha 6 

Name 

arg9 Start Integer 4 

Location 



arg 11 Condition Alpha 1 
Flag 



Alpha 1 



Comments 

The load function to be performed: 
C = Load configuration table 
D = Load device 
P = Load peripheral processor 

New TC line name. Specify X'OO' if none 
(default). Must be present if argl =P. 

Number of the device to be loaded. 

Indicates the type of load to be done: 
T = Load by type 
N = Load by name 
U = Unload to default 
I = Interrupt-driven ("load current") 

Microcode type ID number. Ignored if arg4 = 
Uorl. 

File name for load-by-name. Must be present 
if arg4 = N, otherwise ignored. 

Library name for file named in arg 6. Must be 
present if arg4 = N, otherwise ignored. If 
X'OO', the default microcode library is used. 

Volume name for file named in arg6. Must 
be present if arg4 = N, otherwise ignored. If 
X'OO', the default system volume is used. 

Starting location in the specified device to 
be loaded. Default = 0. Ignored if 
arg4 = I. 

Length of microcode to be loaded. If or 
omitted, the entire microcode file is loaded. 
Ignored if arg4~= I. 

Indicates whether to perform the load if the 
desired microcode is already loaded: 

C = Load conditionally (default) 

U = Load unconditionally. 
Ignored if arg4 = I. 

Indicates whether code is to be renewed on 
DLP/PP error (interrupt-driven call): 
R = Renewable microcode (default) 
N = Nonrenewable microcode 
Optional. 
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Pos Argument Type Size Comments 

arg13 Interrupt Alpha 1 Indicates whether task or system is to 

Flag handle power-on/HELP interrupts: 

S = System handling (default) 
T = Task handling 
Optional. 

arg14 Ret. code Integer 4 Error return code. See Table 3-6 below. 



NOTE 

For FORTRAN programs, the name of this subroutine must be specified as LOADCD. 

Table 3-6. LOADCODE Error Return Codes 



Return 

Code Meaning 

Successful load. 

4 Device/PP specified cannot be programmed. 

8 Specified microcode file not found. (Also set when specified class and 

type of microcode are not included in UCB MC list, or when specified 
file name is not a valid alphanumeric string.) 
1 2 Device/PP not reserved exclusively by the caller. 

1 6 Error in opening microcode file, or file not consecutive. 

20 I/O error when reading microcode file. 

24 One of the following errors : 

1 . I/O error while loading device or PP microcode, or configuration 
tables; 

2. Error when restarting device or PP after loading microcode; 

3. Unable to load device because PP code is missing, or attempt to load 
PP fails for any reason; 

4. Unable to load PP code because configuration tables are missing, or 
attempt to load tables fails for any reason. 

28 Insufficient memory pool (GETMEM failure). 

32 (Reserved) 

36 Incompatible options: 

1. UNLOAD and LOAD-BY-NAME both specified. 

2. CLOAD and INTERRUPT both specified. 

40 Other devices on cluster not all reserved by the calling task 

(non-interrupt-driven LOADCODE only). 
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LOADCODE Subroutine — A COBOL Example 



This program loads microcode for a serial workstation to a combined workstation. 



000100 

000200 

000300 

000400 

000500 

000600 

000700* 

000800* 

000900* 

001000* 

001100' 

001200 

001300 

001400 

001500 

001600 

001700 

001800 

001900 

002000 

002100 

002200 

002300 

002400 

002500 

002600 

002700 

002800 

002900 

003000 

003100 

003200 

003300 

003400 

003500 

003600 

003700 

003800 

003900 



IDENTIFICATION DIVISION. 

PROGRAM- ID. LOADCDEC. 

ENVIRONMENT DIVISION. 

DATA DIVISION. 

WORKING-STORAGE SECTION. 

77 FUNCTION PIC X(2) VALUE "D". 

AS EXPLAINED IN SECTION 2.2.2, COBOL ACCEPTS HALFWORD INTEGERS 

ONLY DEFINE A FOUR-BYTE GROUP ITEM TO BE COMPOSED OF TWO 

HALFWORD-BINARY, ELEMENTARY ITEMS, AND USE THE LOW-ORDER TWO 

BYTES FOR THE INTEGER. TO PASS AN INTEGER TO THE SUBROUTINE, 

INITIALIZE THE HIGH-ORDER BYTES TO ZERO. 

01 DEVICE. 

03 FILLER USAGE IS BINARY VALUE ZERO. 

03 DEVICE-NUMBER USAGE IS BINARY VALUE 3. 

LOAD-TYPE PIC X(l) VALUE "N" . 

CODE-TYPE. 

03 FILLER USAGE IS BINARY VALUE 0. 

03 CODE-ID USAGE IS BINARY VALUE 11. 

FILE-NAME PIC X(8) VALUE ".MC2246S". 

LIB-RARY PIC X(8) VALUE ".SYSTEM.". 

VOL-UME PIC X(6) VALUE "OS". 

START-ADDRESS PIC X(6) VALUE 0. 

RETURNCODE. 

03 FILLER USAGE IS BINARY VALUE 0. 

03 ERROR-CODE USAGE IS BINARY. 
PROCEDURE DIVISION. 
MAIN-PARAGRAPH. 

CALL "LOADCODE" USING FUNCTION, DEVICE, LOAD-TYPE, CODE-TYPE, 
FILE-NAME, LIB-RARY, VOL-UME, START-ADDRESS, RETURNCODE. 

IF ERROR-CODE NOT EQUAL DISPLAY "ERROR-CODE = "ERROR-CODE, 
ELSE DISPLAY "THE NEXT SCREEN WILL BE BLANK. ONLY THE HEL 
"P KEY WILL BE ENABLED." . 
•WHEN THE ENTER KEY IS PRESSED A BLANK SCREEN WILL APPEAR AND ALL 
•KEYS BUT THE HELP KEY WILL BE DISABLED. PRESS HELP AND THEN 
•PRESS PF KEY 1 (CONTINUE) FROM THE COMMAND PROCESSOR MENU. THE 
•NEXT SCREEN WILL BE BLANK WITH ONLY THE CURSOR POSITION, ENTER 
•AND HELP KEYS ENABLED. PRESS ENTER TO CONTINUE. 

DISPLAY "PRESS ENTER TO TERMINATE THE PROGRAM.". 

STOP RUN. 



77 
01 



77 
77 
77 
77 
01 
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LOGOFF 

FUNCTION 

Terminates the user program and logs the user off. 

USAGE No arguments are required. 

NOTE 

If the user program containing the reference to this subroutine is run from a program 
with a Cancel Exit option, the subroutine terminates the program but does not log the 
user off. 
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LOGOFF Subroutine - A BASIC Example 

This example simply calls the LOGOFF subroutine to terminate processing and log the user off. 
000100CALL "LOGOFF" 
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MESSAGE 



FUNCTION 

Allows communication of messages between workstations (tasks). 

Each user who is to receive messages must create a "port" (analogous to a mailbox) 
The user assigns the port a name, which is used to send messages to the creator of the 
port The port is also assigned a buffer size, which is the maximum total s.ze of all 
messages not read ("checked") by the port's creator. 

Users can then transmit messages to that port and the port's creator can check for 
them. The various options for the transmit and check processes are d.scussed in the 
appropriate sections below. 

USAGE (arg 1 , arguments) 

Arg1 defines the message function and determines the number and nature of the 
remaining arguments. 



Pos Argument Type Size 

argl Function Alpha 2 



Comments 

Type of message function: 



CR = Create message port 

DE = Destroy message port 

XM = Transmit message 

XW = Transmit message and wait if 

buffer is full 
CH = Check message port for message 



The remaining arguments depend on the function. 



1 . Create a message port 
Pos Argument Type 

Function 



argl 
arg2 
arg3 



Port Name 

Buffer 
Size 



Alpha 
Alpha 
Integer 



Size Comments 



2 

4 
4 



arg4 Ret. Code Integer 4 



Value is CR 

Name of port to be created. 

Maximum cumulative message size assigned 

to this port (1 -201 4). Optional. Default is 

201 4. When the user checks the messages, 

the cumulative message size is reduced. 

Error return code: 

= Successful creation of port 
4 = Another task is using this port 
8 = This task is using this port 
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2. Destroy a message port 

Pos Argument Type 

argl Function Alpha 2 

arg2 Port Name Alpha 4 

arg3 Ret. Code Integer 4 



Size Comments 



Value is DE 

Name of port to be destroyed. 

Error return code: 

= Successful. 

4 = Successful, but 1 or more waiting 
messages were not received and 
have been lost. 

8 = No such port was created by this 
task. 

If there are any messages in the port, they are lost when the user destroys the port It 
might be appropriate to check the port for messages before destroying it. ' 



3. Transmit a message 

Pos Argument Type 

argl Function Alpha 

arg2 Port Name Alpha 

arg3 Message Alpha 

arg4 Msg Length Integer 

arg5 Ret. Code Integer 



Size Comments 



var 

4 
4 



Value is either XM or XW. With the XW 
function (Transmit-and-Wait), the screen is 
locked until the receiving port is checked 
and this message is received. 

Name of port to which the program trans- 
mits the message. 

Message to be sent. 

Length of the message in characters. 

Error return code: 

Message queued. 
Port named has not been created. 
For argl =XM only Unable to 
insert message into the message 
buffer of the receiving port 
because the buffer is full. 
Port named can only be used by 
privileged code. 




4 
8 



12 = 
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Check message port for message 



Pos Argument Type 

argl Function Alpha 

arg2 Port name Alpha 

arg3 Check Type Alpha 



Size Comments 



2 

4 
1 



arg4 


Time 
Interval 


Integer 


4 


arg5 


Message 
Receiver 


Alpha 


var 


arg6 


Message 
Length 


Integer 


4 



arg7 Ret. Code Integer 



Value is CH 

Name of port to be checked. 

Type of check to perform: 

W = Check and wait until message is 

received 
T = Check and wait until message is 
received or time interval (arg4) has 
expired. 
K = Check and wait until message is 
received or a PF or ENTER key is 
pressed 
B = Check and wait until message is 
received, key is pressed, or time 
expires. 
For K and B options, if the workstation key- 
board is locked, a return code of 1 2 results. 

Time to wait in hundredths of a second. 
Applicable for check types T and B. 

Receiver for message. Its length must be at 
least the value of arg6. 

Length of message receiver. This is the maxi- 
mum length to be returned. The subroutine 
reduces this value to reflect the actual 
message length. If the message is long9r, it 
is truncated. 

Error return code: 

= Message received 
8 = Time interval expired 
1 2 = Keyboard locked, probably by PF 

or ENTER key being pressed 
1 6 = No such port was created by this 
task, or check was canceled (for 
arg3 = T) 



NOTE 



For FORTRAN programs, the name of this subroutine must be specified as MESAGE. 
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MESSAGE Subroutine — A BASIC Example 

This example sets up a message port and demonstrates how the subroutine passes messages 
between workstations. 

000100DIM TYPES 02 

000200DIM P0RTNAME$ 04 

000300DIM MESSAGE1$ 66 

000400DIM MESSAGE2$ 66 

000410DIM MESSAGE3$ 132 

000500DIM CHECKTYPES 01 

000501CHECKTYPE$ = "T" 

000510LOOP: 

000520GOSUB PUTSCREEN 

000530GOSUB DOMESSAGE 

000540GOTO LOOP 

000541 

000550PUTSCREEN: 

000600ACCEPT 

000700 AT (01,12), 

000800"Demonstration of Sending Messages through MESSAGE Subroutine" 
000900 AT (03,03), 

001000"Fill in the following information to either (1) create a message 

001100 port , ' ' , 

001200 AT (04,03), 

001300" (2) destroy a message port, (3) transmit to a port (either retur 

001400n immediately" , 

001500 AT (05,03) , 

001600"or wait until port space is available), or (4) check port forme 

001700ssage. 

001800 AT (07,03) , 

001900 "TYPE: " , 

002000 AT (07,14), TYPES, CH(02), 

002100 AT (07,19), 

002200" (CR-create port; DE-destroy port; XM/XW-t ransmit ; CH-check) " 

002300 AT (08,03), 

002400 "PORTNAME: " , 

002500 AT (08,14), PORTNAMES, CH(04), 

002600 AT (08,19), 

002700" ", 

002800 AT (09,03), 

002900"BUFSIZE: " , 

003000 AT (09,14), BUFSIZE%, PIC (####), 

003100 AT (09,19), 

003200" (1-2014 bytes - for CR) " , 

003300 AT (10,03), 

003400 "MESSAGE: " , 

003500 AT (10,14), MESSAGE1S, CH(66), 

003600 AT (11,14), MESSAGE2$, CH(66), 
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003700 AT (12,03), 

003800"CHECKTYPE: " , 

003900 AT (12,14), CHECKTYPE$, CH(01), 

004000 AT (12,19) , 

004100"(for CH: W-wait ;T-interual wait;K-PFkey wait;B-key & interval)" 

004200 AT (13,03) , 

004300 "INTERVAL: " , 

004400 AT (13,14), INTERVALS PIC(####), 

004500 AT (13,19), 

004600" (for CHECKTYPE=T, time to wait in 1/100 seconds)", 

004700 AT (15,03) , 

004800"RETURN CODE" , 

004900 AT (15,16), RETURNCODE% , PIC(##), 

005000 AT (19,14) , 

005100 ' ' Fill in information and press ENTER for desired action." 

005200RETURN 

005300 

005400DOMESSAGE: 

005410STR(MESSAGE3$,1,66) = MESSAGE1$ 

005420STR(MESSAGE3$,67,66) = MESSAGE2$ 

005500 IF TYPES = "CR" THEN CALL "MESSAGE" ADDR (TYPES , PORTNAME$ , ! 

005600 BUFSIZE%,RETURNCODE%) 

005700 IF TYPES = "DE" THEN CALL "MESSAGE" ADDR (TYPES , PORTNAMES, ! 

005800 RETURNCODE%) 

005900 IF TYPES = "XM" THEN CALL "MESSAGE" ADDR (TYPES , PORTNAMES, ! 

006000 MESSAGE3S , 132%, RETURNCODE%) 

006100 IF TYPES = "CH" THEN CALL "MESSAGE" ADDR (TYPES , PORTNAMES, ! 

006200 CHECKTYPE$,INTERVAL%,MESSAGE3$,132%,RETURNC0DE o /o) 

006310MESSAGE1S = STR(MESSAGE3$ , 1, 66) 

006320MESSAGE2S = STR(MESSAGE3$, 67 ,66) 

006400 RETURN 
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MESSAGE Subroutine — A COBOL Example 



This program creates a port, transmits a message to the port, retrieves and displays the message, 
and destroys the port. 



000100 

000200 

000300 

000400 

000500 

000600 

000700 

000800 

000900 

001000 

001100 

001200 

001300 

001400 

001500 

001600 

001700 

001800 

001900 

002000 

002100 

002200 

002300 

002400 

002500 

002600 

002700 

002800 

002900 

003000 

003100 

003200 

003300 

003400 

003500 

003600 

003700 

003800 

003900 

004000 

004100 



IDENTIFICATION DIVISION. 
PROGRAM-ID. MESSAGC. 
ENVIRONMENT DIVISION. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
77 FUNCTION-TYPE PIC X(2) VALUE "CR". 
77 PORT-NAME PIC X(4) VALUE "FRED". 
77 THE-MESSAGE PIC X(ll) VALUE "THE MESSAGE". 
*AS EXPLAINED IN SECTION 2.2.2, COBOL ACCEPTS HALFWORD INTEGERS 
•ONLY. DEFINE A FOUR-BYTE GROUP ITEM TO BE COMPOSED OF TWO 
•HALFWORD-BINARY, ELEMENTARY ITEMS, AND USE THE LOW-ORDER TWO 
•BYTES FOR THE INTEGER. TO PASS AN INTEGER TO THE SUBROUTINE 
•INITIALIZE THE HIGH-ORDER BYTES TO ZERO. 
01 MESSAGE-LENGTH. 

03 FILLER USAGE IS BINARY VALUE ZERO. 

03 LENGTH-OF-MESSSAGE USAGE IS BINARY VALUE 11. 

CHECK-TYPE PIC X(l) VALUE "W" . 

RECEIVER PIC X(255) VALUE SPACE. 

NEXT ITEM MUST BE CODED BUT IS IGNORED SINCE THE CHECK TYPE 

NOT "T". 
INTERVAL. 

03 FILLER USAGE IS BINARY VALUE ZERO. 

03 TIME-LENGTH USAGE IS BINARY VALUE ZERO. 

RECEIVER-LENGTH. 

03 FILLER USAGE IS BINARY VALUE 

03 LENGTH-OF-RECEIVER USAGE IS 

RETURNCODE. 

03 FILLER USAGE IS BINARY VALUE ZERO. 

03 ERROR-CODE USAGE IS BINARY. 
PROCEDURE DIVISION. 
MAIN-PARAGRAPH. 

PERFORM CREATE-PARAGRAPH. 

PERFORM SEND-PARAGRAPH. 

PERFORM CHECK-PARAGRAPH. 

PERFORM DESTROY-PARAGRAPH. 

STOP RUN. 
CREATE-PARAGRAPH. 

DISPLAY "I AM IN THE CREATE-PARAGRAPH". 

CALL "MESSAGE" USING FUNCTION-TYPE, PORT-NAME, RETURNCODE 

IF ERROR-CODE NOT EQUAL ZERO DISPLAY "ERROR-CODE = " 

ERROR-CODE, ELSE DISPLAY "PORT CREATED". 



77 

77 
•THE 
* IS 

01 



01 



01 



ZERO. 
BINARY VALUE 



255. 
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004200 
004300 
004400 
004500 
004600 
004700 
004800 
004900 
005000 
005100 
005200 
005300 
005400 
005500 
005600 
005700 
005800 
005900 
006000 
006100 



SEND-PARAGRAPH. 

DISPLAY "I AM IN THE SEND-PARAGRAPH." 

MOVE "XM" TO FUNCTION-TYPE. 

CALL "MESSAGE" USING FUNCTION-TYPE, PORT-NAME, THE-MESSAGE, 

MESSAGE-LENGTH, RETURNCODE. 
IF ERROR-CODE NOT EQUAL ZERO DISPLAY "ERROR-CODE = " 
ERROR-CODE, ELSE DISPLAY "MESSAGE DELIVERED". 
CHECK-PARAGRAPH. 

DISPLAY "I AM IN THE CHECK-PARAGRAPH." 
TO FUNCTION-TYPE. 

USING FUNCTION-TYPE, PORT-NAME, CHECK-TYPE, 
INTERVAL, RECEIVER, RECEIVER-LENGTH, RETURNCODE. 
IF ERROR-CODE NOT EQUAL ZERO DISPLAY "ERROR-CODE = " 
ERROR-CODE, ELSE DISPLAY RECEIVER. 
DESTROY-PARAGRAPH. 

DISPLAY "I AM IN THE DESTROY-PARAGRAPH.". 
MOVE "DE" TO FUNCTION-TYPE. 

CALL "MESSAGE" USING FUNCTION-TYPE, PORT-NAME, RETURNCODE. 
IF ERROR-CODE NOT EQUAL ZERO DISPLAY "ERROR-CODE = " 
ERROR-CODE, ELSE DISPLAY "PORT DESTROYED". 



MOVE 
CALL 



"CH" 
"MESSAGE 



MESSAGE-7 



MOUNT 



FUNCTION 

Allows the user to mount a volume. 



USAGE (argl arg11) 

Pos Argument Type Size 

argl Device Integer 4 



arg2 Volume 
arg3 Label 



arg4 Mount 
Usage 



arg5 Drive 
Type 



Alpha 6 
Alpha 1 



Alpha 



Alpha 



arg6 System Alpha 1 

Use Option 



arg7 Bypass 
Option 



Alpha 1 



arg8 No-Msg Alpha 1 

Option 



arg9 No-Display Alpha 1 
Option 



arg10 Address Alpha 1 



Comments 

Device number of the disk or tape to be 
mounted. Must be nonnegative. 

Name of the volume to be mounted. 

Label type: 

S or A = Standard label (default) 

N = No label 

I = IBM label (tape) 

Type of mount: 

S = Shared (default) 

E = Exclusive 

P = Protected (disk) 

R = Restricted removal (disk) 

Type of drive (ignored for tape mount): 
F = Fixed drive 
R = Removable drive (default) 

System files that can be written onto the 
device if the default volume is full (ignored 
for tape mount): 

W= Work files 

S = Spool files 

A = Work and spool files 

N = Neither work nor spool files 
(default) 

Bypass label processing option: 
B = Bypass label 
Blank = Normal mount (default) 

No mount message option: 

N = No message (used when the volume 

is already physically mounted) 
Blank = Normal mount message (default) 

No user display option: 

N = No display 

Blank = Normal mount (default) 
No mount message is displayed at the 
workstation; a message is usually displayed 
at the operator console and the user task 
hangs until the mount is complete. 

Disk addressing option: 
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°P tlon N = Nonstandard (used for non-Wang 

soft-sectored diskette) 
Blank = Standard (default) 

arg11 Ret. Code Integer 4 Error return code. See Table 3-7 below. 

NOTES 

1 . Arguments 3 through 1 are optional; however, if any is included, all preceding 
arguments must be present. Omitted arguments assume the default values speci- 
fied in the argument descriptions. 

2. All arguments must have acceptable values, even if they are ignored. 

Table 3-7. MOUNT Error Return Codes 



Return 

Code Meaning 



Successful mount. 

4 Successful mount, but new volume label type does not agree with input 

parameters. 
8 Successful mount, but new volume name is not the volume name 

requested. 
1 2 Disk or tape I/O error detected while reading new volume label or new 

volume has a bad VTOC. VCBSER set to blank. This return code is set 
when the new volume is physically mounted on the drive but the VCB 
cannot be filled in. 
1 6 Device not disk or tape, or device number invalid. 

20 Device detached. 

24 Disk does not have the requested volume type (fixed or removable). 

28 Request to mount an unlabeled volume on a disk unit other than a 

2270V diskette. 
32 Input volume name blank 

36 Requested volume already mounted on a disk unit, or duplicate volume 

name. 
40 Volume currently in use. 

44 Currently mounted volume reserved by another user for exclusive use. 

48 I/O buffer space insufficient to perform mount. 

52 Unable to allocate space for Tape I/O control blocks. 

56 Invalid request: work and/or spool filing requested in a nonlabeled 

volume. 

60 Invalid request: nonstandard addressing attempted with Standard Label 

option or on hard-sectored device. 

64 Wrong media: soft-sectored diskette inserted into device for hard- 

sectored diskettes only. 

68 Wrong media: hard-sectored diskette inserted into device for soft- 

sectored diskettes only. 

72 Wrong media: hard-sectored diskette inserted for nonstandard 

addressing request. 

76 Wrong addressing mode: caller requested MOUNT for standard 

addressing but diskette is nonstandard. 

80 Device reserved by another user. 

84 MOUNT failed, aborted by user or operator request. 
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MOUNT Subroutine — A COBOL Example 

This program allows the user to mount a nonlabeled diskette. 

000100 IDENTIFICATION DIVISION. 

000200 PROGRAM-ID. MOUNTC. 

000300 ENVIRONMENT DIVISION. 

000400 DATA DIVISION. 

000500 WORKING-STORAGE SECTION. 

000600*AS EXPLAINED IN SECTION 2.2.2, COBOL ACCEPTS HALFW0RD INTEGERS 

000700*ONLY DEFINE A FOUR-BYTE GROUP ITEM TO BE COMPOSED OF TWO 

000800*HALFWORD-BINARY, ELEMENTARY ITEMS, AND USE THE LOW-ORDER TWO 

000900*BYTES FOR THE INTEGER. TO PASS AN INTEGER TO THE SUBROUTINE, 

001000'INITIALIZE THE HIGH-ORDER BYTES TO ZERO. 

001100 01 DEVICE. 

001200 03 FILLER USAGE IS BINARY VALUE 0. 

001300 03 DEVICE-NUMBER USAGE IS BINARY VALUE 23. 

001400 77 VOLUME-NAME PIC X(6) VALUE "FLOPPY". 

001500 77 LABELED PIC X VALUE "N". 

001600 01 RETURN-KODE. 

001700 03 FILLER USAGE IS BINARY VALUE ZERO. 

001800 03 ERROR-CODE USAGE IS BINARY. 

001900 PROCEDURE DIVISION. 

002000 MAIN-PARAGRAPH. 

002100 CALL "MOUNT" USING DEVICE, VOLUME-NAME, LABELED, 

002200 RETURN-KODE. 

002300 IF ERROR-CODE = ZERO DISPLAY "MOUNT SUCCESSFUL" 

002400 ELSE DISPLAY "RETURN CODE = " ERROR-CODE. 

002500 STOP RUN. 
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MOUNT SUBROUTINE - AN RPG II EXAMPLE 



This program instructs the MOUNT subroutine to mount a nonlabeled volume called "ARCHIV" on 
Device 50 of the system. The program checks the return code from the subroutine, displaying it if it 
is nonzero. 



00100FDISPLAY DD F 



WS 



00200C 

00210C* 

00220C* 

00230C* 

00300C 

00400C 

00500C 

00600C 

00700C 

00800C 

00900C 

01000C 

01200C 

01210C* 

01220C* 

01230C* 

01300C 

01400C 

01500C 

01600C 

01700C 

01800C 

01900C 

02000C 

02100C 

02300C 

02310C* 

02320C* 

02330C* 

02400C 

02500C 

02600C 

02700C 



ACCPTSCR1 
PREPARE PARAMETERS TO PASS TO RPGCALL MACRO 



RCODE 



99 

N99 



Z-ADD50 


DEVICE 


40 


MOVE 'ARCHIV 


NAME 


6 


MOVE •H' 


LABEL 


1 


MOVE 'E' 


USAGE 


1 


MOVE 'R' 


TYPE 


1 


MOVE 'W 


WORK 


1 


MOVE ' ' 


BYPASS 


1 


MOVE 'N' 


NOMESS 


1 


Z-ADDO 


RCODE 


40 



EXIT TO RPGCALL MACRO 



EXIT RPGMNT 




RLABL 


DEVICE 


RLABL 


NAME 


RLABL 


LABEL 


RLABL 


USAGE 


RLABL 


TYPE 


RLABL 


WORK 


RLABL 


BYPASS 


RLABL 


NOMESS 


RLABL 


RCODE 



CHECK RETURN CODE 

COMP 
ACCPTSCR3 
ACCPTSCR2 
SETON 



99 



LR 
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02800WSCR1 

02900W 

03000W 

03100W 

03200W 

03400WSCR2 

03500W 

03600W 

03700WSCR3 

03800W 

03900W 

04000W 

04100W 



0707 'PRESS ENTER TO MOUNT A' 

0729 ' NO-LABEL DISKETTE CAL" 

0751 'LED ' 'ARCHIV'" 

0907 'ON SYSTEM DEVICE 50.' 

0707 'MOUNT SUCCESSFUL. PRE' 

0729 'SS ENTER TO END JOB.' 

0707 'MOUNT UNSUCCESSFUL; ' 

0907 'RETURN CODE = ' 

0921RCODE 

1107 'PRESS ENTER TO END JOB' 



RPGMNT 



RPGCALL NAME=RPGMNT , CALL=MOUNT , DEVICE , NAME , LABEL , USAGE , TYPE , C 
WORK, BYPASS, NOMESS, (RC0DE.4.F) 
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PAUSE 

FUNCTION 

Causes a program to pause for a user-specified amount of time. 

USAGE (argD 

Pos Argument Type Size Comments 

arg 1 Time Integer 4 Amount of time to pause, in hundredths of a 

second. 



PAUSE- 1 



PAUSE Subroutine - A FORTRAN Example 

This FORTRAN program first notifies the user that the program is still running, then pauses for one 
second. 

C PROGRAM CODE APPEARS BEFORE THIS STATEMENT 

DO 10 1=1,1000 
C COMPUTATION APPEARS HERE 

IF(I .NE. 500) GO TO 10 

WRITE(0,101) 
C 
C CAUSE A ONE SECOND PAUSE 

CALL PAUSE (100) 
C 

10 CONTINUE 
101 FORMAT ( IX , ' COMPUTING ' ) 
C REMAINDER OF PROGRAM FOLLOWS 
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PRINT 



FUNCTION 

Sends a print file to the print queue. 



USAGE (arg1 r arg2, ...,arg9) 

Pos Argument Type Size 



argl File 
arg2 Library 



Alpha 8 
Alpha 8 



arg3 Volume Alpha 6 



arg4 Mode 



Alpha 1 



arg5 Disposition Alpha 2 



arg6 Copies 

arg7 Print 
Class 



arg8 Form 

Number 



Integer 4 
Alpha 1 

Integer 4 



an 



g9 Ret. code Integer 4 



Comments 

Print file submitted by the program. 

Library on which print file resides. Default is 
SPOOLIB value, as set with PF2 (SET) of the 
Command Processor. 

Volume on which print file resides. Default is 
SPOOLVOL value, as set with PF2 (SET) of 
the Command Processor. 

Print mode: 

S = Spooled (default) 
H = Hold 

Disposition of file after printing: 
DS = Dequeue and save (default) 
DX = Dequeue and scratch 
RS = Requeue and save 

Copies to be printed. Default is 1 . 

Print class. Must be A-Z or blank. Default is 
SET PRTCLASS value, as set with PF2 (SET) 
of the Command Processor. 

Form number. Must be 0-255. Default (if 
omitted or 255) is SET FORM# value, as set 
with PF2 (SET) of the Command Processor. 

Error return code. See Table 3-8 below. 



NOTE 

Arguments 2 through 8 are optional. If omitted, defaults are as specified above. If an 
argument is present, all preceding arguments must also be present. 
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Table 3-8. PRINT Error Return Codes 



Return 




Code 


Meaning 





Successful. 


4 


Volume not mounted. 


8 


Volume in exclusive use. 


12 


All buffers in use, unable to perform verification. 


16 


Library not found. 


20 


File not found. 


24 


Improper file type, or zero records. 


28 


File access denied. 


32 


VTOC error, FDX1 and FDX2 do not agree. 


36 


VTOC error, FDX2 and FDR do not agree. 
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PRINT Subroutine — A BASIC Example 



This program provides a way of submitting print files that are stored on disk to the printer. The user 
simply provides the file, library, and volume names. The program displays the default print mode, the 
disposition of the file after printing, the number of copies, and the form number. The program exe- 
cutes again by flashing the workstation screen briefly and indicating a return code. 

000100DIM FILES 08 

000200DIM LIBRARYS 08 

000300DIM VOLUMES 06 

000400DIM MODES 01 

000500DIM DISPOSITIONS 02 
000600DIM PRINTCLASSS 01 
000700MODES ="S" 

000800DISPOSITIONS ="DS" 
000900COPIES% =0001 

001000FORMNUMBER% =255 
001100 
001200LOOP: 
001300GOSUB PUTSCREEN 
001400GOSUB DOPRINT 
001500GOTO LOOP 
001600 

001700PUTSCREEN: 
001800ACCEPT 
001900 AT (01,14), 

002000"Demonstration of Submit a Print File (PRINT) Subroutine", 
002100 AT (03,03), 

002200 ' ' Fill in the following information to submit a print file via the 
002300 PRINT" , 
002400 AT (04,03), 

002500' 'subroutine: 
002600 AT (06,03), 

002700"FILE: " , 

002800 AT (06,18), FILES, CH(08), 

002900 
003000' 

003100 AT (07,03) 

LIBRARY ' ' ' 

AT (07',18), LIBRARYS, CH(08), 

AT (08,03), 
003500 "VOLUME: 

003600 AT (08,18), VOLUMES, CH(06), 

003700 AT (09,03), 

003800"MODE: " , 

003900 AT (09,18), MODES, CH(01), 

004000 AT (09,29), 

004100" (S-spool; H-hold)", 
004200 AT (10,03), 

004300"DISPOSITION: " , 



AT (06,18), FILES, 
AT (06,29), 
(Print file to be submitted)", 



003200 
003300 
003400 
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004400 AT (10,18), DISPOSITIONS, CH(02), 

004500 AT (10,29), 

004600" (DS-dequeue & saue ;DX-dequeue & scratch ;RS-requeue) " , 

004700 AT (11,03), 

004800"COPIES: " , 

004900 AT (11,18), COPIES%, PIC (####), 

005000 AT (12,03), 

005100 "PRINT CLASS: 

005200 AT (12,18), PRINTCLASSS, CH(01), 

005300 AT (13,03), 

005400 "FORM NUMBER: " , 

005500 AT (13,18), FORMNUMBER%, PIC(###), 

005600 AT (15,03), 

005700" RETURN CODE:", 

005800 AT (15,18), RETURNCODE%, PIC(##) 

005900RETURN 

006000 

006100DOPRINT: 

006200 CALL "PRINT" ADDR(FILE$ , LIBRARYS, VOLUMES, 

006300 MODES, DISPOSITIONS, COPIES%, 

006400 PRINTCLASS$,FORMNUMBER%,RETURNCODE%) 

006500 RETURN 
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PRINT Subroutine — AN RPG II Example 



This program allows the user to print any file in the library #ABCPRT on volume SYSTEM. The user 
can specify the number of copies desired and whether the file should be scratched after printing. 



00200FDISPLAY DD 



WS 



00300C 

00400C 

00410C* 

00500C* 

00600C* 

01000C 

01100C 

01200C 

01210C DISP1 

01220C N88 

01300C 88 

01500C 

01510C* 

01520C* 

01530C* 

01600C 

01700C 

01800C 

01900C 

02000C 

02100C 

02200C 

02300C 

02310C* 

02320C* 

02330C* 

02400C RCODE 

02500C 99 

02600C 



ENBLEKO 
ACCPTSCR1 

PREPARE PARAMETERS TO BE PASSED 

MOVE '#ABCPRT 'LIBR 8 

MOVE 'SYSTEM 'VOLM 6 

MOVE 'S' MODE 1 
COMP 'Y' 

MOVE 'DS' DISP 2 

MOVE 'DX' DISP 2 
Z-ADDO RCODE 40 



* EXIT TO THE RPGCALL MACRO 



EXIT RPGPRT 

RLABL 

RLABL 

RLABL 

RLABL 

RLABL 

RLABL 

RLABL 



FILE 
LIBR 
VOLM 
MODE 
DISP 
COPS 
RCODE 



CHECK THE RETURN CODE 

COMP 

ACCPTSCR2 

SETON 



88 



99 
LR 



02700WSCR1 

02800W 

02900W 

02910W 

03000W 

03100W 

03200W 

03300W 

03400W 

03410W 

03420W 



0707 
0729 
0752 
0915 
1107 
1129 
1315 
1507 
1530 
1715 



'WHICH FILE IN LIBRARY ' 
'#ABCPRT WOULD YOU LIKE' 
'TO PRINT?' 

'HOW MANY COPIES WOULD ' 
'YOU LIKE?' 

'SCRATCH THE FILE AFTER' 
'PRINTING? (Y OR N) ' 



FILE 



COPS 



40 



DISP1 
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03500WSCR2 

03600W 

03700W 

03800W 

03900W 



0707 
0729 

0746RCODE 
0907 



'ERROR IN 
' ; RETURN 



PRINT 
CODE = 



REQUEST' 



'PRESS ENTER TO END JOB 



RPGPRT 



RPGCALL NAME=RPGPRT,CALL=PRINT, FILE, LIBR.VOLM, MODE, DISP, 
(C0PS,4,F),(RC0DE,4,F) 
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PROTECT 



FUNCTION 

Changes the protection attributes of a file or library. 

USAGE (argl, ..., arg5, arg6 [repeatable keyword-value pairs], .... arg8) 
Pos Argument Type Size Comments 

1 



argl 



arg3 
arg4 



Protect 
Range 



Alpha 



arg2 File Name Alpha 8 



Library 
Volume 



Alpha 
Alpha 



8 
6 



Indicates scope of protect change: 
F = Single file 
L = All files in a library 

File whose protect class is to be modified. 
Must be present, but is ignored if argl = L 

Library. 

Volume. 



The following two arguments indicate keyword-value pairs. They can be repeated. 
Pos Argument Type Size Comments 



arg5 


Keyword 


Alpha 


2 


Specifies the file attribute to change. 


arg6 


Value 


Alpha 


var 


New value. 




Keyword 


Recr 
Type 


Recr 
Size 


Receiver 
Value 




ED 


Alpha 


6 


Expiration date, in the form YYMMDD. 




FC 


Alpha 


1 


File protection class. 




ID 


Alpha 


3 


Owner's ID. 


Pos 


Argument 


Type 


Size 


Comments 


arg7 


Limitation 
Flag 


Alpha 


1 


Access rights: 

L = Restricted to the user's access rights 
Blank or omitted = No restriction (use 
the special access rights of the pro- 
gram, if available) 
Optional. 



arg8 Ret. Code Integer 4 



Error return code. See Table 3-9 below. 



NOTE 



For FORTRAN programs, the name of this subroutine must be specified as PROTCT. 
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Table 3-9. PROTECT Error Return Codes 



Return 

Code Meaning 

Successful. 

4 Volume not mounted. 

8 Volume used exclusively by another user. 

1 2 All buffers in use, no protection change. 

1 6 Library not found. 

20 File not found. 

24 Update access denied, no protection change. 

28 (Unused). 

32 File in use, no protection change. 

36 VTOC error. FDX1 and FDX2 do not agree. 

40 VTOC error. FDX2 and FDR do not agree. 

44 Invalid argument list address. 

48 I/O error. VTOC unreliable. 

52 Open or protected files bypassed in protecting library. 

56 Invalid new protection data. 
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PROTECT Subroutine — A BASIC Example 



This program allows the user to protect a previously unprotected single file or an entire library on a 
single volume. The user must also specify the limitation flag, the expiration date, the protect class, 
and the owner of record. 



000100DIM RANGES 01 

000200DIM FILES 08 

000300DIM LIBRARYS 08 

000400DIM VOLUMES 06 

000500DIM LIMITS 01 

000600DIM YY$ 02 

000700DIM MM$ 02 

000800DIM DD$ 02 

000900DIM DATES 06 

001000DIM PROTECTCLASSS 01 

001100DIM OWNERS 03 

001200LOOP: 

001300GOSUB PUTSCREEN 

001400GOSUB PR0TECTIT 

001500GOTO LOOP 

001600 

001700PUTSCREEN: 

001800ACCEPT 

001900 AT (01,24), 

002000"Demonstration of PROTECT Subroutine", 

002100 AT (06,04), 

002200"Enter the information below to protect a file or a library: 

002300 AT (08,03), 

002400 "RANGE: " , 

AT (08,22), RANGES, CH(01), 

AT (08,32), 
(F-file; L-library)", 

AT (09,03), 
FILE:" , 

AT (09,22), FILES, CH(08) 

AT 
' (ignored 



002500 

002600 

002700' 

002800 

002900' 

003000 

003100 

003200' 



003300 AT 
003400 "LIBRARY 
003500 AT 
003600 AT 
003700 "VOLUME: 



(09,22) 
(09,32), 
if RANGE=L) 
(10,03), 



003800 

003900 

004000' 

004100 

004200 

004300' 



AT 
AT 



(10,22) 
(11,03) 

(11,22) 
(12,03) 



LIMITFLAG: " , 

AT (12,22) 
AT (13,03) 

EXPIRATION DATE 



LIBRARYS, 



VOLUMES, 



LIMITS, 



CH(08) 



CH(06) 



CH(01) 
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YY$, 


CH(02) 


MM$, 


CH(02) 


DD$, 


CH(02) 



004400 AT (13,22) 

004500 AT (13,25) 

004600 AT (13,28) 

004700 AT (13,33), 

004800" (YY MM DD) " , 

004900 AT (14,03), 

005000 "PROTECT CLASS: " , 

005100 AT (14,22), PROTECTCLASS$ ,CH (01) , 

005200 AT (15,03) , 

005300"OWNER OF RECORD:", 

005400 AT (15,22), OWNERS, CH(03), 

005500 AT (19,17) , 

005600"Press ENTER to protect either the file or library" 

005700RETURN 

005800 

005900PROTECTIT: 

006000DATE$ = YY$ & MM$ & DD$ 

006100 CALL "PROTECT" ADDR(RANGE$ , FILES , LIBRARY$ , VOLUMES , 

006200 "ED", DATES, 

006300 "FC" .PROTECTCLASSS, 

006400 "ID", OWNERS, 

006500 LIMITS, RETURNCODE%) 

006600 PRINT "RETURN CODE = ": PRINT RETURNCODE% 

006700 PRINT "IF RETURN CODE = SEE IF FILE OR LIBRARY WAS PROTECTED 

006800 STOP 

006900 RETURN 
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PUTPARM 

FUNCTION 

This subroutine has the following primary functions: 

1 . Creates a parameter list (called a Parameter Reference Block, or PRB) to satisfy 
a subsequently generated GETPARM request. 

2. Retrieves a previously created PRB. 

3. Deletes existing PRBs. 
Other functions combine these three. 

USAGE (arg 1 , arguments) 

Argument 1 indicates the PUTPARM function and determines the number and nature of 
other arguments. 

Pos Argument Type Size Comments 

arql Type Alpha 1 Defines the PUTPARM type: 

a D = Create (Display) type 

E = Create (Enter) type 
R = Retrieve and Block type 
M = Retrieve and Merge type 
C = Cleanup type 

Remaining arguments depend on the PUTPARM type selected. A detailed description of 
each type appears below. 

1 . Create a Parameter Reference Block (Type = D or E) 

This type creates a PRB in one of three ways: 

( 1 ) By specifying keywords and values directly ; 

(2) By referencing a previously created PRB and using its keywords and values 
to create the new PRB (see Note 1 for a discussion of a limitation of 
PUTPARM and the use of this feature); and 

(3) By referencing a previously created PRB and merging its keywords and 
values with new keywords and values to create the new PRB. 
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Pos Argument Type Size Comments 



arg! Type 



Alpha 



arg 2 Usage 
Count 



arg3 Prname 



arg6 Value 
arg 7 Length 

arg8 PF Key 
Value 



Integer 



Alpha 8 



arg4 Keyword Integer 4 

Count 



arg 5 Keyword Alpha 8 



Alpha 
Integer 

Alpha 



var 
4 

1 



arg9 PRB Label Alpha 8 



arg 10 Reference Alpha 8 
Label 



argil Cleanup 
Option 



Alpha 1 



Value is D or E. D causes a GETPARM screen 
to be displayed when the PUTPARM call is 
encountered and allows the user to modify 
keyword values. E causes no GETPARM 
interaction; the user-specified PF key indi- 
cates the action desired. These types corre- 
spond to the DISPLAY and ENTER Procedure 
language statements. 

Number of times the PRB can be used: 
= Use generated PRB an unlimited 

number of times. 
Other = Use generated PRB arg2 times. 
Range is 1 to 32768, default is 1 . 
Optional. 

Prname of associated GETPARM request to 
be satisfied. Cannot begin with X'OO'. 

Number of keywords to be associated with 
this PRB. Arg5-arg7 contain the names and 
values for these keywords. Range is to 
255. 

Name of keyword. Arg5-arg7 are repeated 
the number of times specified in arg4. 

Value of keyword. 

Length of value (arg6) in characters. Range 
is 1 to 256. 

Indicates PF key associated with the PRB. If 
omitted, the default value is "@" (ENTER). 
See Table 3-18 for AID values. 

Label to be generated for the PRB. If omitted, 
or if the label field begins with a blank or 
X'00', no label is generated. 

Label of previously defined PRB, whose key- 
words are to be used in this reference. If this 
argument begins with a blank or X'OO', or is 
omitted, no "backward reference" is made 
and the new PRB will be generated directly 
from arguments 5-7. 

Arg4=0: The program uses all keyword/- 
value fields in the backward referenced PRB 
to generate a new PRB. 
Arg4#0: The program creates a PRB con- 
sisting of keywords and values specified in 
args 5-7, updated by values of identical key- 
words in referenced PRB. 

Indicates action to take after reference to a 
backward referenced PRB (see arg 10): 
C = Delete backward referenced PRB 
after reference. 
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Pos Argument Type Size Comments 

Blank = Retain backward referenced PRB. 
Ignored if no backward reference is speci- 
fied. 
arg12 Ret. Code Integer 4 Error return code. See Table 3-10 below. 

Arguments 4 through 1 1 are optional; however, if any of them is present all preceding 
ones must be included (with the exception of Arguments 5 through 7, which must be 
omitted if arg4=0). Argument 2 can be omitted even if other arguments are specified. 

2. Retrieve a previously created parameter reference block (R type) 

This type allows the program to examine keywords/values of a previously created PRB, 
whose values are generally provided for a GETPARM screen request. This ophon does 
not create a new PRB; the PRB must have been created earlier in the program (at this 
level) and must be labeled. This type is generally used to pass file references. 

Pos Argument Type Size Comments 



argl 
arg2 



Type 
PRB Label 



Alpha 
Alpha 



1 
8 



arg3 Receiver 

arg4 Receiver 
Length 



Alpha var 
Integer 4 



arg5 Total 
Length 



Integer 



arg6 PFKey Alpha 1 

Receiver 



arg7 Cleanup Alpha 1 

Option 



an 



g8 Ret. Code Integer 4 



Value is R 

Label of the previously created PRB that is to 

be retrieved and examined. 

Receiver for the keyword fields in the pre- 
viously created PRB. Ignored if arg4=0. 

Total length of the receiver (arg3). The sub- 
routine returns the PRB fields in the receiver 
in the order in which they are defined in the 
PRB, as follows: 

Byte 1-8— Keyword 

9-12— Keyword field length 
1 3-end— Keyword field data; length 
indicated in bytes 9-12 
This sequence of bytes repeats until the 
receiver is filled, or until all keyword fields 
are transferred. Arg4 is adjusted to reflect 
the actual number of bytes used. 

Total length required by the receiver to hold all keyword 
field information. If the receiver is large enough to hold 
all the data, this value will be identical to the value of arg4 
on return from the subroutine. 

Indicates the PF key receiver from the referenced PRB. 
See Note 4 for a problem with this feature. Optional. See 
Table 3-1 8 for AID byte values. 

Indicates the action to take after the PRB has been refer- 
enced: 

C = Delete PRB after fields are extracted 

Blank = Retain PRB 

Error return code. See Table 3-10 below. 
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Arguments 3 through 7 are optional; however, if any of them is present, all preceding 
arguments must be included. Arguments 3 and 4 must both be either included or 
omitted. 



3. Retrieve a previously created PRB (M type) 

The M type allows the program to obtain keyword values from a GETPARM screen It is 
generally used to pass file references. The M type is identical in function to the R type- it 
differs only in the manner in which values in the PRB are returned to the caller. 

Pos Argument Type Size Comments 



argl Type Alpha 1 

arg2 PRB Label Alpha 8 



arg3 Keyword 
Count 



Integer 4 
arg4 Keyword Alpha 8 



arg5 Receiver Alpha var 



Value is M 

Label of the previously created PRB that is to 
be examined. 

Number of keywords whose values are to be 
merged. Each is specified in arguments 4-6. 

Keyword name. Arguments 4-6 are repeated 
the number of times specified in arg3. 

Receiver for the value of the keyword speci- 
fied in arg4. If this keyword is found in the 
"backward referenced" PRB, the receiver 
contains the value as follows: 

If the PRB field is longer than the length of 

arg5, the leftmost arg6 characters are 

returned. 

If the PRB field is shorter than arg5, it will 

be placed left-justified into the field, with 

the remainder of the field set to blanks. 



arg6 Length Integer 4 Length of the receiver in characters (arg5). 



arg7 PF Key Alpha 1 

Receiver 



arg8 Cleanup Alpha 1 

Option 



Receiver for the PF key value from the refer- 
enced PRB. See Note 4 for a problem with 
this feature. Optional. See Table 3-18 for 
AID values. 

Indicates action to take after reference to 

the PRB: 

C = Delete value after reference 
Blank = Retain value after reference 

arg9 Ret. code Integer 4 Error return code. See Table 3-10 below. 

Arguments 3 through 8 are optional; however, if any of them is present, all preceding 
arguments must be included. 



4. Delete ("cleanup") old parameter reference blocks (C type) 

This type causes PRBs created by the program to be removed. 
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Pos Argument Type 



argl 
arg2 



Type 
PRB Label 



Alpha 
Alpha 



Size Comments 

1 Value is C 

8 Label of PRB to delete. Optional. If omitted, 

or if the first byte is blank or X'OO', all PRBs 
at this level are deleted. 



arg3 Ret. Code Integer 4 Error return code. See Table 3- 10 below. 

NOTES 

1 Only the PUTPARM user's program can examine or delete a PRB that it has created 
(via PUTPARM type E or D). This refers specifically to "backward references 
(types R and M, and the backward reference option of types E and D) and to 
"cleanups" (type C and the cleanup option of types E, D, R, and M). 

2 A PRB created by the user program can be used to satisfy a GETPARM screen that 
is exactly one link level beyond it (i.e., in a program linked to, via LINK, by the 
PUTPARM user's program). 

There are situations in which it is desirable to get around this limitation. For 
instance, a user menu program might wish to link to another menu which, in turn, 
runs the COPY utility. The first menu cannot directly create parameters for the 
COPY screens, since two link levels separate them. However, if the second menu 
does a PUTPARM type E or D for each of the COPY screens, and specifies a label 
(arq9) for each of the PRBs, the first menu can create parameters for each of the 
second menu's PRBs just as if it were a GETPARM screen. The only difference is 
that the "prname" argument (arg3) in the first menu's PUTPARM should be 
replaced by the "label" assigned by the second menu. Also, the second menu need 
not specify any keyword fields in the PRBs, since any fields specif ted by the first 
menu are simply added to the second menu's PRBs. The following example helps 
to clarify this. 

Two BASIC programs might contain the following statements: 
(First menu program, called MENU1) 

TAI I "PUTPARM" ADDR ("E", "LABLNAME", 3%, "FILE ", FILES, 8%, 

"LIBRARY'' LIBRARY!. -8%. "VOLUME ", VOLUMES, 6%, RETC0DE%) 
CALL "LINK" ADDR ("MENU2 ", CMPC0DE%, RETC0DE%) 

(Second menu program, called MENU2) 

CALL "PUTPARM" ADDR ("E", "INPUT ", 0%, "@" , "LABLNAME", 

RETC0DE%) n „ nnnca ,^ 

CALL "LINK" ADDR ("COPY ", CMPC0DE%, RETC0DE%) 

This example allows the first menu to create parameters for COPY'S input screen 
with FILES LIBRARY$, and VOLUMES even though MENU2 is performing the 
LINK. LABLNAME is used as the PRB label in MENU2 and as the pseudo- prname 
inMENUL 

The program can use this method of "chaining" PUTPARMs across as many link 
levels as desired. 
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3. The old B and F options have been replaced by the R and M options, respectively. 
The new options perform the same functions, but their argument lists have been 
modified. The B and F options still work, but will probably be removed at some 
point in the future; programs using these options should be modified appropri- 
ately. 

4. For FORTRAN programs, the name of this subroutine must be specified as 
PUTPRM. 



Table 3-1 0. PUTPARM Error Return Codes 



Return 

Code Meaning 

Successful. 

4 Backward referenced label not found. 

8 Bad format list supplied. 

1 2 Error found in a previous PRB. 

1 6 Invalid input parameter while using "cleanup" (C) parameter option. 

20 Invalid input parameter while using M or R option. 
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PUTPARM Subroutine — A COBOL Example 



This program allows the user to enter file, library, and volume names for corresponding fields of the 
EDITOR'S Input screen. After calling PUTPARM. the program links dynamically to the EDITOR by call- 
ing the LINK subroutine. When the EDITOR'S Input screen appears, the file, library, and volume fields 
contain the values entered by the user. 



000100 

000200 

000300 

000400 

000500 

000600 

000700 

000800 

000900 

001000 

001100 

001200 

001300 

001400 

001500 

001600 

001700 

001800 

001900 

002000 

002100 

002200 

002300 

002400 

002500 

002600 

002700 

002800 

002900 

003000 

003100 

003200 

003300 

003400 

003500 

003600 

003700 

003800 

003900 

004000 

004100 

004200 



77 
77 
01 



"THE 



IDENTIFICATION DIVISION. 
PROGRAM-ID. PUTPARMC. 
ENVIRONMENT DIVISION. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
*THE FOLLOWING ITEMS ARE THE ARGUMENTS FOR THE PUTPARM SUBROUTINE 
TY-PE PIC X VALUE "D" . 
PRNAME PIC X(8) VALUE "INPUT". 
KEYWORD-COUNT. 

03 FILLER USAGE IS BINARY VALUE 0. 
03 WORD-COUNT USAGE IS BINARY VALUE 4. 
NEXT TWO ITEMS INITIALIZE THE LANGUAGE FIELD OF THE 
•EDITOR INPUT SCREEN TO "C" FOR COBOL. 
77 KEYWORD-1 PIC X(9) VALUE "LANGUAGE". 
77 LANGUAGE PIC X(9) VALUE "C". 
•AS EXPLAINED IN SECTION 2.2.2, COBOL ACCEPTS HALFW0RD INTEGERS 
•ONLY DEFINE A FOUR-BYTE GROUP ITEM TO BE COMPOSED OF TWO 
•HALFWORD-BINARY, ELEMENTARY ITEMS, AND USE THE LOW-ORDER TWO 
•BYTES FOR THE INTEGER. TO PASS AN INTEGER TO THE SUBROUTINE, 
•INITIALIZE THE HIGH-ORDER BYTES TO ZERO. 
01 LENGTH-1. 

03 FILLER USAGE IS BINARY VALUE 0. 

03 COUNT-1 USAGE IS BINARY VALUE 9. 

KEYWORD-2 PIC X(8) VALUE "FILE". 

FILE-NAME PIC X(8) VALUE SPACE. 

LENGTH-2. 

03 FILLER USAGE IS BINARY VALUE 0. 

03 COUNT-2 USAGE IS BINARY VALUE 8. 

KEYWORD-3 PIC X(8) VALUE "LIBRARY". 

LIB-RARY PIC X(8) VALUE SPACE. 

LENGTH-3. 

03 FILLER USAGE IS BINARY VALUE 0. 

03 COUNT-3 USAGE IS BINARY VALUE 8. 

KEYWORD-4 PIC X(8) VALUE "VOLUME". 

VOL-UME PIC X(6) VALUE SPACE. 

LENGTH-4. 

03 FILLER USAGE IS BINARY VALUE 0. 

03 COUNT-4 USAGE IS BINARY VALUE 6. 

PRB-LABEL PIC X(8) VALUE "EDITPARM". 

RETURN-KODE. 

03 FILLER USAGE IS BINARY VALUE ZERO. 

03 ERROR-CODE USAGE IS BINARY. 



77 
77 
01 



77 
77 
01 



77 
77 
01 



77 
01 
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004300 

004400 

004500 

004600 

004700 

004800 

004900 

005000 

005100 

005200 

005300 

005400 

005500 

005600 

005700 

005800 

005900 

006000 

006100 

006200 

006300 

006400 

006500 

006600 

006700 

006800 

006900 

007000 

007100 

007200 

007300 

007400 

007500 

007600 

007700 

007800 

007900 



*THE 
77 
77 
77 
77 
01 



ITEMS ARE THE ARGUMENTS FOR 
"EDITOR" . 
'S" . 



THE LINK SUBROUTINE 



77 
77 
01 



01 



01 



'RETURN TO PUTPARMC 



FOLLOWING 

LINKNAME PIC X(8) VALUE 
LOCATION PIC X(l) VALUE 
LINK-LIBRARY PIC X(8). 
LINK-VOLUME PIC X(6) . 
PARAMETERS. 

03 FILLER USAGE IS BINARY VALUE 0. 
03 PARAMETER-COUNT USAGE IS BINARY VALUE 0. 
EXIT-OPTION PIC X VALUE "C". 
PF16-MESSAGE PIC X(18) VALUE 
MESSAGE-LENGTH. 
03 FILLER BINARY VALUE 0. 
03 FILLER BINARY VALUE 18. 
COMPLETION. 

03 FILLER USAGE BINARY VALUE ZERO. 
03 COMPLETION-CODE USAGE BINARY. 
ERRORS. 

03 FILLER USAGE BINARY VALUE ZERO. 
03 LINK-ERROR-CODE USAGE BINARY VALUE ZERO. 
PROCEDURE DIVISION. 
MAIN-PARAGRAPH. 

ACCEPT FILE-NAME, LIB-RARY, VOL-UME. 
CALL "PUTPARM" USING TY-PE, PRNAME, KEYWORD-COUNT, 
KEYWORD-1, LANGUAGE, LENGTH-1, KEYWORD-2, FILE-NAME, 
LENGTH-2, KEYWORD-3, LIB-RARY, LENGTH-3, KEYWORD-4 
VOL-UME, LENGTH-4, RETURN-KODE. 
IF ERROR-CODE NOT EQUAL ZERO, GO TO PUTPARM-ERROR . 
CALL "LINK" USING LINKNAME, LOCATION, LINK-LIBRARY 
LINK-VOLUME, PARAMETERS, EXIT-OPTION 
PF16-MESSAGE, MESSAGE-LENGTH, 
COMPLETION, ERRORS. 
IF COMPLETION-CODE = 8 DISPLAY "LINK-ERROR-CODE IS " 

LINK-ERROR-CODE, ELSE DISPLAY "YAYI" 
STOP RUN. 
PUTPARM-ERROR. 

DISPLAY "PUTPARM ERROR-CODE = " ERROR-CODE 
STOP RUN. 
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PUTPARM Subroutine — AN RPG II Example 



This program calls the PUTPARM subroutine four times. Each time, PUTPARM is used to supply 
parameters for one of the GETPARM screens displayed by the COPY utility. The program then calls 
the LINK subroutine to link to the COPY utility. In the COPY utility, the file EXPENSES in library 
ABCDATA on volume SYSTEM is copied to a file called EXPENSE2 in the same library. The user does 
not see any of COPY'S GETPARM screens, since the PUTPARM type is E (Enter) rather than D 
(Display). 



00100FDISPLAY DD F 

00200C 

00210C* 

00220C* 

00230C* 

00300C 

00400C 

00500C 

00600C 

00700C 

00800C 

00900C 

01000C 

01100C 

01200C 

01300C 

01400C 

01500C 

01600C 

01700C 

01800C 

01810C* 

01820C* 

01830C* 

01900C 

02000C 

02100C 

02200C 

02300C 

02400C 

02500C 

02600C 

02700C 

02800C 

02900C 

03000C 

03100C 

03200C 

03300C 

03400C 

03500C 



WS 
ACCPTSCR1 

PREPARE PARAMETERS TO PASS DURING FIRST PUTPARM CALL *"' 



MOVE 'E' 


TYPE 


1 


MOVE 'INPUT 


'PRN 


8 


Z-ADD4 


KCNT 


40 


MOVE 'FILE 


'KEYl 


8 


MOVE 'EXPENSES 


'VAL1 


8 


Z-ADD8 


LEN1 


40 


MOVE 'LIBRARY 


'KEY2 


8 


MOVE 'ABCDATA' 


VAL2 


7 


Z-ADD7 


LEN2 


40 


MOVE 'VOLUME 


'KEY3 


8 


MOVE 'SYSTEM' 


VAL3 


6 


Z-ADD6 


LEN3 


40 


MOVEL'COPY 


'KEY4 


8 


MOVE 'FILE' 


VAL4 


4 


Z-ADD4 


LEN4 


40 


Z-ADDO 


RCOD 


40 



EXIT TO RPGCALL MACRO 



EXIT RPGPTA 




RLABL 


TYPE 


RLABL 


PRN 


RLABL 


KCNT 


RLABL 


KEYl 


RLABL 


VAL1 


RLABL 


LEN1 


RLABL 


KEY2 


RLABL 


VAL2 


RLABL 


LEN2 


RLABL • 


KEY3 


RLABL 


VAL3 


RLABL 


LEN3 


RLABL 


KEY4 


RLABL 


VAL4 


RLABL 


LEN4 


RLABL 


RCOD 
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03510C* 

03520C* 

03530C* 

03600C 

03700C 

03710C* 

03720C* 

03730C* 

03800C 

03900C 

04000C 

04010C* 

04020C* 

04030C* 

04100C 

04510C* 

04520C* 

04530C* 

04600C 

04700C 

04710C* 

04720C* 

04730C* 

04800C 

04900C 

05000C 

05100C 

05101C* 

05110C* 

05120C* 

05200C 

06150C* 

06155C* 

06160C* 

06200C 

06300C 

06310C* 

06320C* 

06330C* 

06400C 

06500C 

06600C 

06700C 

06710C* 

06720C* 

06730C* 

06800C 

06900C 

06920C* 

06930C* 

06940C* 

07000C 

07100C 



CHECK RETURN CODE *** 



RCOD 



10 



COMP 
GOTO ERRS 



10 



PREPARE PARAMETERS TO PASS DURING SECOND PUTPARM CALL 

MOVE 'OPTIONS 'PRN 

Z-ADDO KCNT 

Z-ADDO RCOD 

,## EXIT TO RPGCALL MACRO *** 

EXIT RPGPTB 

*** CHECK RETURN CODE ** # 



RCOD 



20 



COMP 
GOTO ERRS 



20 



# ** PREPARE PARAMETERS TO PASS DURING THIRD PUTPARM CALL *' 

MOVE 'OUTPUT 'PRN 
Z-ADD3 KCNT 
MOVE 'EXPENSE2'VAL1 
Z-ADDO RCOD 

*•' EXIT TO RPGCALL MACRO *** 

EXIT RPGPTC 

*** CHECK RETURN CODE ### 



RCOD 



30 



COMP 
GOTO ERRS 



30 



*** PREPARE PARAMETERS TO PASS DURING FOURTH PUTPARM CALL * 



MOVE ' EOJ 


'PRN 


Z-ADDO 


KCNT 


MOVE ' P* 


PFK 


Z-ADDO 


RCOD 



RCOD 



40 



EXIT TO RPGCALL MACRO 

EXIT RPGPTD 

RLABL PFK 

' CHECK RETURN CODE *** 

COMP 
GOTO ERRS 



40 
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07101C* 

07110C* 

07120C* 

07200C 

07300C 

07400C 

07500C 

07510C* 

07520C* 

07530C* 

07600C 

07700C 

07800C 

07900C 

08000C 

08010C* 

&8020C* 

08030C* 

08100C 

08200C 

08300C N50 

08310C* 

08320C* 

08330C* 

08400C 

08500C 

08600C 

08700C 

08800WSCR1 

08900W 

09000W 

09100W 

09200WSCR2 

09300W 

09400W 

09500W 

09600W 

09700W 

09800W 

09900W 

10000W 

101OOW 

10200W 

10300W 

10400W 



PREPARE PARAMETERS TO PASS DURING LINK CALL 



MOVE 'COPY 
MOVE 'S' 
Z-ADDO 
Z-ADDO 



'PROG 
LTYPE 
CCODE 
RCODE 



8 
1 

40 
40 



EXIT TO RPGCALL MACRO 



EXIT RPGPTE 

RLABL 

RLABL 

RLABL 

RLABL 



PROG 
LTYPE 
CCODE 
RCODE 



* CHECK COMPLETION AND RETURN CODES 



CCODE 
RCODE 



COMP 
COMP 
GOTO END 



50 
50 



* DISPLAY ERROR MESSAGE SCREEN 



ERRS 
END 



TAG 

ACCPTSCR2 
TAG 
SETON 



LR 



1207 
1229 
1251 

N50 0707 

10 0729 

20 0729 

30 0729 

40 0729 

N50 1010 

N50 1025RCOD 

50 0707 

50 1010 

50 1030CCODE 

50 1210 

50 1225RC0DE 



'PRESS ENTER TO COPY TH ' 
'E EXPENSES FILE INTO A' 
' FILE CALLED EXPENSE2. ' 



'ERROR IN 
'DEFINING 
'DEFINING 
'DEFINING 
'DEFINING 



PUTPARM CALL 
INPUT. ' 
OPTIONS. ' 
OUTPUT. ' 
EOJ. ' 



'RETURN CODE = ' 

'ERROR IN LINK CALL. 
'COMPLETION CODE = ' 

'RETURN CODE = ' 
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RPGPTA: 



RPGPTB 



RPGPTC: 



RPGPTD: 



RPGPTE 



RPGCALL NAME=RPGPTA,CALL=PUTPARM,TYPE,PRN, (KCNT.4.F), C 

KEY1 I VAL1,(LEN1,4,F),KEY2,VAL2, ( LEN2 , 4 , F) , KEY3 , VAL3 , 
(LEN3,4,F),KEY4,VAL4, (LEN4,4,F), (RC0D,4,F) C 



RPGCALL NAME=RPGPTB,CALL=PUTPARM,TYPE,PRN, (KCNT,4,F) , 
(RC0D,4,F) 



RPGCALL NAME=RPGPTC,CALL=PUTPARM,TYPE,PRN, (KCNT , 4 , F) , KEY1 , C 
UAL1, (LEN1 I 4.F),KEY2,VAL2, ( LEN2 , 4 , F) , KEY3 , VAL3 , 
(LEN3.4.F), (RC0D,4,F) C 



RPGCALL NAME=RPGPTD,CALL=PUTPARM,TYPE,PRN, (KCNT,4,F) ,PFK, C 
(RC0D.4.F) 



RPGCALL NAME=RPGPTE,CALL=LINK,PROG,LTYPE, (CC0DE,4,F) , 
(RC0DE,4,F) 
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READFDR 



FUNCTION 

Obtains information about a specified file. READFDR can return specified control blocks 
or various characteristics about the file. The control blocks and characteristics appear 
below. 



USAGE (arg1,...,arg4, arguments) 

Arg1 through arg3 identify the file about which information is obtained. Arg4 defines 
the function to be performed and the number and nature of the additional arguments. 



Pos Argument Type Size 

argl File Alpha 8 



arg2 Library 
arg3 Volume 
arg4 Function 



Alpha 8 
Alpha 6 
Integer 4 



Comments 

File whose FDR(s) and/or AXD1 are to be 
retrieved. 

Library containing the file. 

Volume being accessed. 

Type of information to be returned: 

= Return specified control blocks 

1 = Return FDR 1 

2 = Return FDR2 

3 = Return FDR1 and FDR2 

4 = Return AXD1 

5 = Return FDR1 andAXDI 

6 = Return FDR2 andAXDI 

7 = Return FDR1 and FDR2 and AXD1 



The remaining arguments depend on the function type. 



Return specified control blocks (arg4 is nonzero) 



Pos Argument Type Size 

arg5 Receiver Alpha var 



arg6 Ret. Code Integer 4 



Comments 

Data item that receives the blocks specified 
in arg4. Its length depends on which blocks 
are returned. FDR1 and FDR2 are 80 bytes 
each. AXD1 is 60 bytes plus 28 bytes for 
each alternate key. The maximum length for 
AXD1 is 2048 bytes. The order in which the 
blocks are received is specified in arg4. 

Error return code. See Table 3-1 1 below. If 
the return code is nonzero, only FDR1 and 
FDR2 are returned. 
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2. Return specified fields (arg4 is zero) 

Each of the keywords is Alpha (2). Definitions of the type and contents of the receivers 
appear in the following list. The last argument in the argument list (arg5) must be the 
error return code. 



Recr Recr Receiver 

Keyword Type Size Value 

AC Integer 4 Number of defined alternate keys. 

AX Alpha var Alternate key information entry. Must be at least 1 2 

times the number of alternate keys. This information 
is not available if the return code (arg5) is nonzero. 
Each entry is 1 2 bytes and consists of the following : 
Byte 1-2— Alternate key number. 

3-4— Position of the key field in record. 
5-6— Key length. 
7— Duplicates flag: 

D = Duplicate alternate keys 

allowed 
Blank = Duplicates not allowed 
8— Compression flag: 

C = Key entries are compressed 
Blank = Key entries not com- 
pressed 
9-12— Number of records on this alternate 
key path. 

Number of blocks allocated to the file. 

Number of blocks used by the file. 

Creation date of the file, in the form YYMMDD. 

Data packing factor. 

Number of extents allocated to the file. 

Expiration date of the file, in the form YYMMDD. 

Starting and ending sectors of the extents allocated 
to the file, listed in pairs of 4-byte integer entries. The 
length of the EL receiver must be at least eight times 
the value of the EA receiver. 

Alpha 1 File protection class. 

Alpha 1 File type: 

C = Consecutive 

I = Indexed 

P = Print 

O = Object program 

A = Alternate indexed 

L =Log 

W= Word processing document 



BA 


Integer 


4 


BC 


Integer 


4 


CD 


Alpha 


6 


DP 


Integer 


4 


EA 


Integer 


4 


ED 


Alpha 


6 


EL 


Alpha 


var 



FC 
FT 
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Recr Recr Receiver 

Keyword Type Size Value 

ID Alpha 3 File creator's ID. 

IP Integer 4 Index packing factor. 

KP Integer 4 Position of the first byte of the primary key (counting 

from 1). 

KS/KL Integer 4 Length of the primary key. 

MD Alpha 6 Date of the last modification to the file, in the form 

YYMMDD. 

ME Alpha 4 Special execute access flags for the file. 

MR Alpha 4 Special read access flags for the file. 

MW Alpha 4 Special write access flags for the file. 

PF Alpha 1 Partial file indicator, created by BACKUP utility: 

P = Partial file 
Blank = Normal file 

RC Integer 4 Number of records in the file. 

RS Integer 4 Size of the records in the file. For fixed length 

records, this is the actual size. For variable length 
records, this is the specified maximum size. 

RT Alpha 1 Record type: 

F = Fixed-length 
V = Variable-length 
C = Compressed 



Pos Argument Type Size 

arg5 Ret. Code Integer 4 



Comments 

Error return code. Code 1 00, 1 04, or 1 08 
returned only for an unsuccessful attempt to 
access AXD1 and only if no error has 
occurred in attempting to access FDR1 and 
FDR2. See Table 3-1 1 below. 



NOTE 

For FORTRAN programs, the name of this subroutine must be specified as RDFDR. 
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Table 3-11. READFDR Error Return Codes 



Return 




Code 


Meaning 





Operation performed successfully. 


4 


Volume not mounted. 


8 


Volume used exclusively by another user. 


12 


All buffers in use. 


16 


Library not found. 


20 


File label not found. 


32 


VTOC error. FDX1 and FDX2 do not agree. 


36 


VTOC error. FDX2 and FDR do not agree. 


40 


Invalid input parameters. 


44 


Disk I/O error. VTOC unreliable. 


100 


Possession conflict. 


104 


Protection violation. 


108 


Partial BACKUP file (cannot be opened). 
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READFDR Subroutine — A COBOL Example 

This program accepts file, library, and volume names specified by the user. It also returns the number 
of blocks allocated for the file, the number of blocks used, the number of extents allocated, and the 
file's data packing factor. 

000100 IDENTIFICATION DIVISION. 

000200 PROGRAM-ID. READFDRC. 

000300 ENVIRONMENT DIVISION. 

000400 DATA DIVISION. 

000500 WORKING-STORAGE SECTION. 

000600 77 FILE-NAME PICX(8). 

000700 77 LIB-RARY PIC X(8) . 

000800 77 V0L-UME PIC X(6) . 

000900*AS EXPLAINED IN SECTION 2.2.2, COBOL ACCEPTS HALFW0RD INTEGERS 

001000*ONLY DEFINE A FOUR-BYTE GROUP ITEM TO BE COMPOSED OF TWO 

001100*HALFWORD-BINARY, ELEMENTARY ITEMS, AND USE THE LOW-ORDER TWO 

001200'BYTES FOR THE INTEGER. TO PASS AN INTEGER TO THE SUBROUTINE, 

001300'INITIALIZE THE HIGH-ORDER BYTES TO ZERO. 

001400 01 FUNCTION. 

001500 03 FILLER USAGE IS BINARY VALUE ZERO. 

001600 03 FUNCTION-CODE USAGE IS BINARY VALUE 0. 

001700 77 BLOCKS-ALLOCATED PIC X(2) VALUE "BA". 

001800 01 NUMBER-ALLOCATED. 

001900 03 FILLER USAGE IS BINARY VALUE ZERO. 

002000 03 ALLOCATED USAGE IS BINARY. 

002100 77 BLOCKS-USED PIC X(2) VALUE "BC". 

002200 01 NUMBER-USED. 

002300 03 FILLER USAGE IS BINARY VALUE ZERO. 

002400 03 USED USAGE IS BINARY. 

002500 77 EXTENT-KEY PIC X(2) VALUE "EA". 

002600 01 EXTENT-NUMBER. 

002700 03 FILLER USAGE IS BINARY VALUE ZERO. 

002800 03 EXTENTS USAGE IS BINARY. 

002900 77 DATA-PACK-KEY PIC X(2) VALUE "DP". 

003000 01 DATA-PACK-NUMBER. 

003100 03 FILLER USAGE IS BINARY VALUE ZERO. 

003200 03 DATA-PACK USAGE IS BINARY. 

003300 01 RETURNC0DE. 

003400 03 FILLER USAGE IS BINARY VALUE ZERO. 

003500 03 ERROR-CODE USAGE IS BINARY. 
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003600 PROCEDURE DIVISION. 

003700 FIRST-PARAGRAPH. 

003800 ACCEPT FILE-NAME, LIB-RARY, VOL-UME. 

003900 IF FILE-NAME = "ABC" GO TO EXIT-PARAGRAPH. 

004000 CALL "READFDR" USING FILE-NAME, LIB-RARY, VOL-UME, FUNCTION 

004100 BLOCKS-ALLOCATED, NUMBER-ALLOCATED, 

004200 BLOCKS-USED, NUMBER-USED, EXTENT-KEY, EXTENT-NUMBER, 

004300 DATA-PACK-KEY, DATA-PACK-NUMBER, RETURNCODE. 

004400 IF ERROR-CODE NOT = DISPLAY "RETURN CODE = "ERROR-CODE 

004500 GO TO EXIT-PARAGRAPH. 

004600 DISPLAY "ALLOCATED = "ALLOCATED, 

004700 " USED = "USED, 

004800 " EXTENTS = "EXTENTS, 

004900 " DATA-PACK = "DATA-PACK. 

005000 GO TO FIRST-PARAGRAPH. ■ 

005100 EXIT-PARAGRAPH. 

005200 STOP RUN. 
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READVTOC 



FUNCTION 

Provides information from the Volume Table of Contents (VTOC). The available informa- 
tion includes the following: 

Files in a specified library 

Libraries on a specified volume 

Standard label volumes on the system 

Free extents on a volume 

General information about a volume 

Specified VTOC blocks 

Files and free extents on a volume 



USAGE (arg 1 , arguments) 

Arg1 defines the function to be performed and the number and nature of the additional 
arguments. 

1 . Obtain the names of files in a specified library 



Pos 


Argument 


Type 


Size 


Comments 


argl 


Function 


Alpha 


1 


Value is F 


arg2 


Library 


Alpha 


8 


Library containing the files. 


arg3 


Volume 


Alpha 


6 


Volume being accessed. 


arg4 


Starter 


Integer 


4 


File entry at which to begin 



arg5 Counter 



arg 6 Receiver 



arg 7 
arg8 



Ret. Code 
File Count 



nonnegative. Value of is treated as 1 . 

Integer 4 Number of file entries to list. Must be non- 

negative. If fewer entries are returned than 
specified, arg 5 is set to the actual number of 
entries returned. 

Alpha var Data item that receives the file entries. The 

length must be at least eight times the value 
of arg 5. Each entry is 8 bytes and contains 
one file name. 

Integer 4 Error return code. See Table 3- 1 2 below. 

Integer 4 Number of files in the specified library. 
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2. Obtain the names of libraries on a specified volume 



Pos Argument Type Size Comments 



argl 
arg2 
arg3 



arg6 
arg7 



Function 

Volume 

Starter 



arg4 Counter 



arg5 Receiver 



Ret. Code 

Library 
Count 



Alpha 1 Value is L 

Alpha 6 Volume containing the libraries. 

Integer 4 Library entry at which to begin listing. Must 

be nonnegative. A value of is treated as 1 . 

Integer 4 Number of library entries to list. Must be 

nonnegative. If fewer entries are returned 
than specified, arg4 is set to the actual 
number of entries returned. 

Alpha var Data item that receives the library entries. 

The length must be at least 1 times the 
value of arg4. Each library entry is 1 bytes 
and contains the library name (the first 8 
bytes) and the number of files in the library 
(the last 2 bytes). 

Integer 4 Error return code. See Table 3- 1 2 below. 

Integer 4 Number of libraries on the specified volume. 



3. Obtain the names of standard label (SL) volumes on the system 
Pos Argument Type Size Comments 



arg 1 Function 
arg2 Starter 

arg3 Counter 



arg4 Receiver 



arg 5 Volume 



Alpha 1 Value is V 

Integer 4 Volume entry at which to begin listing. Must 

be nonnegative. A value of is treated as 1 . 

Integer 4 Number of volume entries to list. Must be 

nonnegative. If fewer entries are returned 
than specified, arg3 is set to the actual 
number of entries returned. 

Alpha var Data item that receives the volume entries. 

The length must be at least 1 6 times the 
value of arg3. Each item is 1 6 bytes and is 
structured as follows: 
Byte 1-6— Volume name. 
7-8- X'OO' (unused). 
9-10— Total number of libraries. 
1 1-12— Total number of files. 
13-16— Error return code. See Table 3-12 
below. If the return code is nonzero. 
Bytes 9-1 2 are not set. 

Integer 4 Number of SL disk volumes on the system. 
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Obtain the locations of free extents on a volume 



Pos Argument Type 



argl 
arg2 
arg3 



arg6 
arg7 



Function 

Volume 

Starter 



arg4 Counter 



arg5 Receiver 



Ret. Code 
Extents 



Alpha 
Alpha 
Integer 

Integer 



Alpha 



Integer 
Integer 



Size Comments 



1 Value is X 

6 Volume whose free extents are to be listed. 

4 Relative order of the entry at which to begin 

the listing. A value of is treated as 1 . 

4 Number of extent entries to list. Must be non- 

negative. If fewer entries are returned than 
specified, arg4 is set to the actual number of 
entries returned. 

var Data item that receives the extent entries. 

Must be at least eight times the value of 
arg4. Each entry consists of two four-byte 
integers containing the starting and ending 
block numbers for the extent. 

4 Error return code. See Table 3- 1 2 below. 

4 Number of free extents on the specified 

volume. 



Obtain general information about a volume 



Pos 


Argument 


Type 


Size 


Comments 


argl 


Function 


Alpha 


1 


Value is G 


arg2 


Volume 


Alpha 


6 


Volume whose VTOC is being read 


arg3 


Keyword 


Alpha 


2 


Type of information to be returned 



arg4 Receiver 



Integer 



Each arg3 must be paired with arg4 and can 
be repeated. 

Receives the information specified by arg3. 
Each arg4 must be paired with arg3. The 
keywords and information received are as 
follows. 



Keyword Contents of receiver 



BC 
BF 
DC 

FC 
LC 
PC 

VC 



Number of blocks on the volume available to the user. 

Number of free user blocks on the volume. 

Number of blocks on the volume, not including the spare 
cylinder. 

Number of files on the volume. 

Number of libraries on the volume. 

Number of physical blocks on the volume, including the spare 
cylinder. 

Number of blocks in the VTOC. 
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Keyword Contents of receiver 

VF Number of free blocks in the VTOC. The maximum value 

returned is 255; therefore, for large disks, this result may be 
meaningless. (A value of exactly 255 can probably be dismissed 
as incorrect.) 

XF Number of free user extents on the volume. 



Pos Argument Type Size 

arg5 Ret. Code Integer 4 



Comments 

Error return code. See Table 3-12 below. 



6. Obtain specified VTOC blocks 
Pos Argument Type Size 

arg! Function Alpha 1 



arg2 
arg3 



arg6 
arg7 



Volume 
Starter 



arg4 Counter 



arg5 Receiver 



Ret. Code 
Blocks 



Alpha 
Integer 

Integer 
Alpha 



Integer 
Integer 



6 
4 



var 



4 
4 



Comments 

Value is # 

Volume whose VTOC is being read. 

Entry at which to begin listing. Must be non- 
negative. A value of is treated as 1 . 

Number of VTOC blocks to return. Must be 
nonnegative. If fewer blocks are returned, 
arg5 is set to the number of blocks returned. 

User file UFB (file number in BASIC, or FD in 
COBOL) which receives the VTOC blocks 
requested. The file must consist of 
2048-byte records and must be open in 
Output mode; there should be as least as 
much space in the file as specified by arg4. 
Any existing records in the file are destroyed. 

Error return code. See Table 3-12 below. 

Number of blocks in the VTOC. 



Obtain the names of files and the locations of free extents on a volume 



Pos Argument Type 



argl 
arg2 
arg3 

arg4 



Function 

Volume 

File 
Starter 

File 
Counter 



Alpha 
Alpha 
Integer 

Integer 



Size Comments 

1 Value is D 

6 Volume whose VTOC is to be read. 

4 Relative order of VTOC entry at which to 

begin listing. Must be nonnegative. Value of 
is treated as 1 . 

4 Number of file names to return. Must be non- 

negative. If fewer entries are returned, arg4 
is set to the number of entries returned. 
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Pos 

arg5 



Argument Type Size Comments 



File 
Receiver 



Alpha var 



arg6 Extent 
Starter 

arg7 Extent 
Counter 



arg8 Extent 
Receiver 



Integer 4 
Integer 4 

Alpha var 



arg9 Ret. Code Integer 4 
arg10 Files Integer 4 



arg 1 1 Extents 



Integer 4 



FD name (COBOL) or file number (BASIC) of 
a file that receives the entries for the files on 
the volume. This file must be open in either 
Output or Extend mode; on return from the 
subroutine, it is open in Extend mode. The 
records in the file must consist of 1 82-byte 
consecutive records and will have the follow- 
ing structure: 

Byte 1-6— Volume name 

7-14— Library name 
15-22— Filename 
23-1 02- FDR1 record for the file 
1 03- 1 82 - FDR2 record for the file, 
or zeroes if none 

Free extent at which to begin listing. 
Optional. 

Number of free extent entries to return. 
Optional. If fewer entries are returned than 
specified, arg6 is set to the actual number of 
entries returned. 

FD name (COBOL) or number (BASIC) of the 
file that receives the entries. Optional. This 
file must be open in Output or Extend mode 
and consists of 8-byte consecutive records. 
Bytes 1 to 4 contain the starting block 
number of a free extent; bytes 5 to 8 contain 
the ending block number. Upon return from 
the subroutine, this file is open in the Extend 
mode. 

Error return code. See Table 3-1 2 below. 

Number of files on the volume, computed 
from the VTOC blocks. 

Number of free extents on the volume, 
computed from the VTOC blocks. Optional. 
See Note 1 . 



Arguments 6 through 8 and 1 1 must all be either present or absent. These options can 
be used for VTOC verification, since the free extent information and the file information 
are extracted from the same VTOC state. If verification is not desired or if the VTOC is 
guaranteed to be unchanging, the programmer can use the X function (function 4) to 
retrieve the same free extent information without requiring a user file for the output. 



NOTES 

1 . This subroutine makes two important assumptions: 

(a) That the disk volume has a readable VTOC; otherwise, the results are not 
predictable and the user file records and/or free extent records might con- 
tain incorrect information. 
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(b) That the current structure of the VS VTOC is the basis for the subroutine. 
Should this change in a future release, a new version of the subroutine 
would be required to ensure correct processing of this option. 

2. For FORTRAN programs, the name of this subroutine must be specified as 
RDVTOC. 

3. The General Information option (G) replaces the Extends option (B), which con- 
tinues to be supported. 



Table 3-12. READVTOC Error Return Codes 


Return 




Code 


Meaning 





Successful. 


4 


Invalid argument list address. 


8 


Volume not mounted. 


12 


Volume used exclusively by another user. 


16 


All buffers in use. 


20 


Volume specified is nonlabeled. 
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READVTOC Subroutine — A COBOL Example 



This program retrieves the names of the files in a library specified by the user. Ten files are read 
simultaneously. The program also returns the number of files in the library. Output appears on the 
workstation. 



000100 

000200 

000300 

000400 

000500 

000600 

000700 

000800 

000900* 

001000* 

001100* 

001200* 

001300* 

001400 

001500 

001600 

001700 

001800 

001900 

002000 

002100 

002200 

002300 

002400 

002500 

002600 

002700 

002800 

002900 

003000 

003100' 

003200* 

003300 

003400 

003500 

003600 

003700 

003800 

003900 

004000 

004100 

004200 

004300 

004400 

004500 

004600 

004700 



IDENTIFICATION DIVISION. 

PROGRAM-ID. RDVTOCC. 

ENVIRONMENT DIVISION. 

DATA DIVISION. 

WORKING-STORAGE SECTION. 

77 TY-PE PIC X VALUE "F" . 

77 LIB-RARY PIC X(8) . 

77 VOL-UME PIC X(6) . 

AS EXPLAINED IN SECTION 2.2.2, COBOL ACCEPTS HALFW0RD INTEGERS 

ONLY. DEFINE A FOUR-BYTE GROUP ITEM TO BE COMPOSED OF TWO 

HALFWORD-BINARY, ELEMENTARY ITEMS, AND USE THE LOW-ORDER TWO 

BYTES FOR THE INTEGER. TO PASS AN INTEGER TO THE SUBROUTINE, 

INITIALIZE THE HIGH-ORDER BYTES TO ZERO. 

01 STARTER. 

03 FILLER USAGE IS BINARY VALUE ZERO. 

03 STARTNUMBER USAGE IS BINARY. 

C0UN-TER. 

03 FILLER USAGE IS BINARY VALUE 0. 

03 COUNTNUMBER USAGE IS BINARY. 

RECEIVER PIC X(80) . 

RETURNCODE. 

03 FILLER USAGE IS BINARY VALUE ZERO. 

03 RETURNVALUE USAGE IS BINARY. 

FILE-COUNT. 

03 FILLER USAGE IS BINARY VALUE ZERO. 

03 FILECOUNT USAGE IS BINARY. 
PROCEDURE DIVISION. 
MAIN- PARAGRAPH. 

ACCEPT LIB-RARY, VOL-UME. 

IF LIB-RARY = "X" GO TO STOP-PARAGRAPH. 
COUNTNUMBER MUST BE INITIALIZED WHENEVER A NEW LIBRARY IS READ, 
SINCE THE VALUE RETURNED MAY THE LESS THAN THE ORIGINAL. 

MOVE 10 TO COUNTNUMBER. 

PERFORM CALL-PARAGRAPH VARYING STARTNUMBER FROM 1 BY 10 
UNTIL COUNTNUMBER LESS THAN 10. 

GO TO STOP-PARAGRAPH. 
CALL-PARAGRAPH. 

MOVE SPACES TO RECEIVER. 

CALL "READVTOC" USING TY-PE, LIB-RARY, VOL-UME, STARTER, 
COUN-TER, RECEIVER, RETURNCODE, FILE-COUNT. 

IF RETURNVALUE NOT = DISPLAY "RETURN CODE = "RETURNVALUE, 
GO TO STOP-PARAGRAPH. 

DISPLAY RECEIVER. 

IF STARTNUMBER = 1 DISPLAY "FILECOUNT = "FILECOUNT. 

DISPLAY "COUNTNUMBER = "COUNTNUMBER. 
STOP-PARAGRAPH. 

STOP RUN. 



01 



77 
01 



01 
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RENAME 



FUNCTION 

Allows the user to rename a file or library, with the options of bypassing expiration date 
checking and limiting access rights for a program with special privileges. 



USAGE (arg1,...,arg10) 

Pos Argument Type Size 

argl Type Alpha 1 

arg2 File Name Alpha 8 



arg3 Library 

arg4 Volume 
arg5 New File 
arg6 New Lib. 

arg7 Bypass 
Flag 



arg8 Access 
Limit Flag 



Alpha 8 



Alpha 
Alpha 
Alpha 

Alpha 



Alpha 



6 
8 
8 



arg9 Allow- Alpha 1 

OPEN Flag 



arg10 Ret. Code Integer 4 



Comments 

Type of rename: Specify F to rename a file, L 
to rename a library,-G to rename a file across 
library boundaries (specify new file and 
library names). 

Name of the file to be renamed. Ignored if 
arg1=L 

Rename library: 

Arg1=F: Library where file resides. 

Arg1=L orG: Library to be renamed. 

Volume where library resides. 

New file name. 

New library name. Optional, but required for 
library rename. 

Indicates whether to bypass expiration date 

checking. Optional. 
B = Bypass checking 
Blank = Do not bypass checking. 

Access rights to the new file or library: 
L = Restrict rights to the access rights of 

the program user. 
Blank = Allow full access privileges. 

Optional. 

Rename-when-open option: 

O = Allow rename when open 

Blank = Do not allow rename 
Optional. 
Error return code. See Table 3-1 3 below. 



RENAME- 1 



NOTES 

1 The user cannot rename a library that contains a file for which the user does not 
have update access rights. 

2. Any arguments that are omitted have the default values associated with the user. 

3. Arguments 6 through 9 are optional, but if any of them is present, all preceding 
arguments must also be present. 



Table 3-13. RENAME Error Return Codes 



Return 

Code Meaning 

File or library renamed. 

4 Volume not mounted. 

8 Volume used exclusively by other user. 

1 2 All buffers in use, no rename. 

1 6 Library not found. 

20 File not found. 

24 Update access to some file protection class in the library denied, no 

rename. 

28 Unexpired file, no rename. 

32 File in use, no rename. 

36 VTOC error. FDX 1 and FDX2 do not agree. 

40 VTOC error. FDX2 and FDR do not agree. 

44 Invalid argument list address. 

48 I/O error. VTOC unreliable. 

52 New file name or library name already exists, no rename. 

56 New file name invalid, or first character is #, no rename. 

60 VTOC currently full. Insufficient space for new FDX1/FDX2. 

64 Reserved bits in parameter list options byte are nonzero. 
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RENAME Subroutine — A COBOL Example 



This program allows the user to change the name of a file whose retention period might not have 
expired. Argument 7 is omitted because access rights are not restricted. 



000100 

000200 

000300 

000400 

000500 

000600 

000700 

000800 

000900 

001000 

001100 

001200 

001300* 

001400' 

001500' 

001600 

001700 

001800 

002900 

002000 

002100 

002200 

002300 

002400 

002500 

002600 

002700 

002800 

002900 

003000 

003100 

003200 

003300 

003400 



IDENTIFICATION DIVISION. 
PROGRAM-ID. RENAMEC. 
ENVIRONMENT DIVISION. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
77 FUNCTION PIC X VALUE "G". 
77 FILE-NAME PIC X(8) . 
77 LIB-RARY PIC X(8) . 
77 VOL-UME PIC X(6) . 
77 NEW-NAME PIC X(8). 
77 EXPIRE-CHECK PIC X VALUE "B". 
*AS EXPLAINED IN SECTION 2.2.2, COBOL ACCEPTS HALFW0RD INTEGERS 
*0NLY DEFINE A FOUR-BYTE GROUP ITEM TO BE COMPOSED OF TWO 
•HALFWORD-BINARY, ELEMENTARY ITEMS, AND USE THE LOW-ORDER TWO 
BYTES FOR THE INTEGER. 
01 RETURNC0DE. 

03 FILLER USAGE IS BINARY VALUE ZERO. 

03 ERROR-CODE USAGE IS BINARY. 
PROCEDURE DIVISION. 
FIRST-PARAGRAPH. 

ACCEPT FILE-NAME, LIB-RARY, VOL-UME, NEW-NAME. 

IF FILE-NAME = "ABC" GO TO EXIT-PARAGRAPH. 

PERFORM CALL-PARAGRAPH. 
CALL-PARAGRAPH. 

CALL "RENAME" USING FUNCTION, FILE-NAME, LIB-RARY, VOL-UME, 
NEW-NAME, EXPIRE-CHECK, RETURNCODE. 

IF ERROR-CODE NOT EQUAL ZERO GO TO ERROR-PARAGRAPH. 

DISPLAY "TO VERIFY USE PF KEY 5 FROM THE COMMAND PROCESSOR." 

GO TO FIRST-PARAGRAPH. 
ERROR-PARAGRAPH. 

DISPLAY "ERROR-CODE = "ERROR-CODE. 

GO TO FIRST-PARAGRAPH. 
EXIT-PARAGRAPH. 

STOP RUN. 
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RENAME Subroutine - A FORTRAN Example 

This example is a general purpose, interactive program that allows the user to rename a file or library 
by providing names during program execution. 

LOGICAL'l TYPE, EXP, LIM 

REAL*8 FILE, LIB, VOL, NEW 
C RCODE IS THE RETURN CODE FOR THE SUBROUTINE 

INTEGER RCODE 
C ASK THE USER FOR THE NECESSARY INPUTS 

PRINT 101,' RENAME FILE (F) OR LIBRARY (L)?' 

READ(0,103) TYPE 

IFCTYPE .EQ. 'L')G0 TO 10 

PRINT 101,' ENTER NAME OF FILE TO BE RENAMED' 

READ(0,102) FILE 

PRINT 101,' ENTER NAME OF LIBRARY' 

READ(0,102) LIB 

GO TO 20 
10 PRINT 101, « ENTER LIBRARY TO BE RENAMED' 

READ(0,102) LIB 
20 PRINT 101,' ENTER VOLUME NAME' 

READ(0,102) VOL 

PRINT 101, " ENTER NEW FILE/LIBRARY NAME' 

READ(0,102) NEW 
C SET EXPIRATION DATE AND ACCESS LIMITS 

EXP = 'B' 

LIM = 'L' 
C 
C CALL THE RENAME SUBROUTINE 

CALL RENAME (TYPE, FILE, LIB, VOL, NEW, EXP, LIM, RCODE) 
C 
C PRINT THE RETURN CODE 

PRINT 104, RCODE 

101 F0RMAT(A35) 

102 FORMAT (A8) 

103 FORMAT(Al) 

104 FORMAT (IX, 'RETURN CODE = '14) 
PAUSE 

END 
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WANG 



Help Us Help You 



Customer Comment Form 



Title. 



VS USERSUBS REFERENCE 



Publications NnmhAr 800-1 31 5US-01 



We've worked hard to make this document useful, readable, and technically accurate. Did we succeed? Only you can tell us! 
Your comments and suggestions will help us improve our technical communications. Please take a few minutes to let us 
know how you feel. 



How did you receive this publication? 

D Support or □ Don't know 

Sales Rep 
D Wang Supplies □ Other 

Division 

D From another 

user 

□ Enclosed 

with equipment 



How did you use this Publication? 



□ Introduction 
to the subject 

D Classroom text 
(student) 

□ Classroom text 
(teacher) 

□ Self-study 
text 



□ Aid to advanced 
knowledge 

D Guide to operating 
instructions 

□ As a reference 
manual 

□ Other 



Please rate the quality of this publication in each of the following areas. 



VERY 
EXCELLENT GOOD FAIR POOR POOR 



Technical Accuracy — Does the system work the way the manual says it does? □ 

Readability — Is the manual easy to read and understand? □ 

Clarity — Are the instructions easy to follow? □ 

Examples — Were they helpful, realistic ? Were there enough of them ? □ 

Organization — Was it logical? Was it easy to find what you needed to know? O 

Illustrations — Were they clear and useful ? D 

Physical Attractiveness — What did you think of the printing, binding, etc? D 

Were there any terms or concepts that were not defined properly? D YD N If so, what were they? 

After reading this document do you feel that you will be able to operate the equipment/software? □ Yes □ No 

□ Yes, with practice 

What errors or faults did you find in the manual? (Please include page numbers) 



D 


D 


□ 


a 


□ 


□ 


a 


a 


□ 


□ 


□ 


a 


□ 


□ 


□ 


a 


□ 


□ 


□ 


□ 


□ 


□ 


□ 


a 


□ 


□ 


a 


a 


jthev 


? 







Do you have any other comments or suggestions?. 



Name. 
Title _ 



Dept/Mail Stop 
Company 



Thank you for your help. 



Street. 
City 



State/Country . 
Zip Code 



Telephone. 



All comments and suggestions become the property of Wang Laboratories, Inc. 



Printed in U.S.A. 14-3140 3-82-5C 



WANG 
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LOWELL. MA 
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WANG LABORATORIES, INC. 
CHARLES T. PEERS, JR., MAIL STOP 1 363 
ONE INDUSTRIAL AVENUE 
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RETURN 

FUNCTION 

Allows the user to return through several levels of subroutine calls. 



USAGE (arg1,arg2) 

Pos Argument Type 

argl Level Integer 

Count 



Size 

4 



arg2 Ret. Code Integer 4 



Comments 

Number of levels to pass through. If zero, 
the subroutine does a simple return. If posi- 
tive, the subroutine returns to that number 
of levels from the calling program. However, 
it always stops at either the Command Pro- 
cessor or the next lower LINK level, if this 
argument is too large. 

Return code from the calling program. 
Optional. (0 if omitted.) 



NOTES 

1 This subroutine can be used in a program that has several subroutine layers; when 
called from an inner routine, it allows the program to return to an outer level, 
bypassing intermediate levels. This is typically done when an error condition exists 
and a user wants to bypass further processing and return directly to another step 
(e.g., an initial menu or error handler). 

2 Note that the RETURN subroutine can operate only within subroutine levels of the 
same program (the same object file). If the level count is larger than the current 
nesting level of subroutine CALLs, it causes an unlink back to the linking program 
(or Command Processor). It does not go any further, however, regardless of level 
count (thus, it can never interfere with the logic of any program other than the 
user's own). 
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RETURN Subroutine — A COBOL Example 



In the following three programs, control passes from RETURN 1 to RETURN2 to RETURN3 via the 
CALL statement. It then passes from RETURN3 to RETURN 1 , bypassing RETURN2, via the RETURN 
subroutine called from RETURN3. 

000100 IDENTIFICATION DIVISION. 

000200 PROGRAM-ID. RETURN1. 

000300 ENVIRONMENT DIVISION. 

000400 DATA DIVISION. 

000500 PROCEDURE DIVISION. 

000600 MAIN-PARAGRAPH. 

000700 DISPLAY "THIS IS LEVEL 1.". 

000800 CALL "RETURN2" . 

000900*THE NEXT STATEMENT WILL BE EXECUTED AFTER THE RETURN SUBROUTINE 

001000 # PASSES CONTROL BACK TO RETURN1C FROM RETURN3C 

001100 DISPLAY "THIS IS LEVEL 1 AGAIN." 

001200 STOP RUN. 



000100 IDENTIFICATION DIVISION. 

000200 PROGRAM-ID. RETURN2. 

000300 ENVIRONMENT DIVISION. 

000400 DATA DIVISION. 

000500 PROCEDURE DIVISION. 

000600 MAIN-PARAGRAPH. 

000700 DISPLAY "THIS IS LEVEL 2. 

000800 CALL "RETURN3" . 

000900*THE NEXT STATEMENT WOULD BE 

001000*TO THIS LEVEL FROM RETURN3. 

001100 DISPLAY "THIS IS LEVEL 

001200 GOBACK. 

001300 EXIT PROGRAM. 



EXECUTED IF CONTROL WERE PASSED BACK 
2 AGAIN. " . 



.2.2, COBOL 
GROUP ITEM 



000100 IDENTIFICATION DIVISION. 

000200 PROGRAM-ID. RETURN3. 

000300 ENVIRONMENT DIVISION. 

000400 DATA DIVISION. 

000500 WORKING-STORAGE SECTION. 

000600*AS EXPLAINED IN SECTION 2 

000700*ONLY. DEFINE A FOUR-BYTE 

000800*HALFWORD-BINARY, ELEMENTARY ITEMS 

000900*BYTES FOR THE INTEGER. TO PASS AN 

OOIOOO'INITIALIZE THE HIGH-ORDER BYTES TO 

001100 01 LEVEL-COUNT. 

001200 03 FILLER USAGE IS BINARY VALUE 

001300*THE NEXT ITEM IS INITIALIZED TO 2 

001400 # RETURN SUBROUTINE TO PASS CONTROL 

001500 03 LEVELCOUNT USAGE IS BINARY 

001600 PROCEDURE DIVISION. 

001700 MAIN-PARAGRAPH. 

001800 DISPLAY "THIS IS LEVEL THREE.". 

001900 CALL "RETURN" USING LEVEL-COUNT. 

002000 GOBACK. 

002100 EXIT PROGRAM. 



ACCEPTS HALFWORD INTEGERS 
TO BE COMPOSED OF TWO 

THE LOW-ORDER TWO 
TO THE SUBROUTINE, 



AND USE 
INTEGER 
ZERO. 

0. 
IN ORDER TO INSTRUCT THE 
BACK THAT MANY LEVELS. 
VALUE 2. 
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SCRATCH 



FUNCTION 

Provides the ability to scratch a file or library. It has the options of bypassing expiration 
date checking and limiting access rights for a program with special privileges (as 
described in system security documentation). 



USAGE (arg1,...,arg7) 

Pos Argument Type Size 

argl Type Alpha 1 

arg2 File Name Alpha 8 

arg3 Library Alpha 8 



arg4 Volume Alpha 6 

arg5 Expiration Alpha 1 
Check 



arg6 Access Alpha 

Limit Flag 



arg7 Ret. Code Integer 4 



Comments 

Type of scratch: 
F = File scratch 
L = Library scratch 

File to be scratched. Must be included, but 
ignored if argl =L 

Scratch library: 

Arg 1 =F: Library where file resides 

Arg1=L: Library to scratch 

Volume where library resides. 

Indicates whether or not to bypass expiration 
date checking: 

B = Bypass checking 

Blank/omitted = No bypass 
Optional. Must be included if arg6 is 
included. 

Access rights for the file or library: 

L = Restrict access rights 

Blank/omitted = Full access 
The program cannot scratch a file or a library 
containing a file that the user does not have 
access rights to. Optional. If present, arg5 
must be included. 

Error return code. See Table 3-14 below. 



NOTES 

1 . Scratching the only file in a library results in scratching the library. 

2. For FORTRAN programs, the name of this subroutine must be specified as 
SCRTCH. 
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Table 3-14. SCRATCH Error Return Codes 



Return 




Code 


Meaning 





File or library scratched from volume. 


4 


Volume not mounted. 


8 


Volume used exclusively by another user. 


12 


All buffers in use, no scratch. 


16 


Library not found. 


20 


File not found. 


24 


Update access to file protection class denied (single file scratch 




only). 


28 


Unexpired file, no scratch (single file scratch only). 


32 


File in use, no scratch. 


36 


VTOC error. FDX1 and FDX2 do not agree. 


40 


VTOC error. FDX2 and FDR do not agree. 


44 


Invalid argument list address. 


48 


I/O error. VTOC unreliable. 


52 


Open, protected, and/or unexpired filets) bypassed in scratching 




library. 
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SCRATCH Subroutine — A COBOL Example 

This program allows the user to scratch a file or library, bypassing the check of the expiration period. 

000100 IDENTIFICATION DIVISION. 

000200 PROGRAM-ID . SCRATCHC . 

000300 ENVIRONMENT DIVISION. 

000400 DATA DIVISION. 

000500 WORKING-STORAGE SECTION. 

000600 77 FUNCTION-TYPE PIC X. 

000700 77 FILE-NAME PICX(8). 

000800 77 LIB-RARY PIC X(8) . 

000900 77 VOL-UME PIC X(6) . 

001000 77 EXPIRE-CHECK PIC X VALUE "B". 

001100*AS EXPLAINED IN SECTION 2.2.2, COBOL ACCEPTS HALFWORD INTEGERS 

001200*ONLY. DEFINE A FOUR-BYTE GROUP ITEM TO BE COMPOSED OF TWO 

001300*HALFWORD-BINARY, ELEMENTARY ITEMS, AND USE THE LOW-ORDER TWO 

001400*BYTES FOR THE INTEGER. 

001500 01 RETURNCODE. 

001600 03 FILLER USAGE IS BINARY VALUE ZERO. 

001700 03 ERROR-CODE USAGE IS BINARY. 

001800 PROCEDURE DIVISION. 

001900 FIRST-PARAGRAPH. 

002000 ACCEPT FUNCTION-TYPE, FILE-NAME, LIB-RARY, VOL-UME. 

002100 IF FUNCTION-TYPE = "Z" GO TO EXIT-PARAGRAPH. 

002200 PERFORM CALL-PARAGRAPH. 

002300 CALL-PARAGRAPH. 

002400 CALL "SCRATCH" USING FUNCTION-TYPE, FILE-NAME, LIB-RARY, 

002500 VOL-UME, EXPIRE-CHECK, RETURNCODE. 

002600 IF ERROR-CODE NOT = DISPLAY "RETURN CODE = "ERROR-CODE, 

002700 GO TO EXIT-PARAGRAPH. 

002800 DISPLAY "TO VERIFY USE PF KEY 5 FROM THE COMMAND PROCESSOR." 

002900 GO TO FIRST-PARAGRAPH. 

003000 EXIT-PARAGRAPH. 

003100 STOP RUN. 
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SCRATCH Subroutine - A FORTRAN Example 



This program allows the user to scratch a file or library. The user must provide the file, library, and 
volume names. 

C 'FNAME', 'LNAME', AND 'VNAME' ARE FILE, LIBRARY, AND VOLUME NAMES 

REAL*8 FNAME, LNAME, VNAME 

L0GICAL*1 OPTION, EXPIRE, ACCESS 

INTEGER RCODE 
C USER PROVIDES NECESSARY FILE, LIBRARY, VOLUME NAMES 

WRITE(0,101) ' ENTER F TO SCRATCH FILE, L TO SCRATCH LIBRARY' 

READ(0,102) OPTION 

IF(0PTI0N .EQ. 'F') WRITE(0,101) ' ENTER FILE NAME' 

IF(0PTI0N .EQ. 'F') READ(0,103) FNAME 

WRITE (0,101) ' ENTER LIBRARY NAME' 

READ (0,103) LNAME 

WRITE(0,101) ' ENTER VOLUME NAME' 

READ (0,104) VNAME 
C SET EXPIRATION DATE AND ACCESS LIMITATION OPTIONS 

EXPIRE = 'B' 

ACCESS = ' ' 
C 
C CALL SCRATCH SUBROUTINE (SCRTCH IN FORTRAN) 

CALL SCRTCH (OPTION, FNAME, LNAME, VNAME, EXPIRE, ACCESS, RCODE) 
C 
C WRITE RETURN CODE TO WORKSTATION 

WRITE(0,105) RCODE 

101 FORMAT(A50) 

102 FORMAT (AD 

103 FORMAT(A8) 

104 FORMAT(A6) 

105 FORMAKIX, 'RETURN CODE = ',14) 
PAUSE 

END 
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SCRATCH Subroutine - An RPG II Example 



This program allows the user to scratch any file or library on the system. The program displays the 
return code if it is greater than 0. 
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ACCPTSCR1 
** PREPARE PARAMETERS TO BE PASSED *** 
FILE 



COMP ' 
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MOVE ' L' 


TYPE 


1 


MOVE 'F' 


TYPE 


1 


Z-ADDO 


RCODE 


40 
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EXIT TO RPGCALL MACRO # " 



EXIT RPGSCR 




RLABL 


TYPE 


RLABL 


FILE 


RLABL 
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RLABL 


VOLM 


RLABL 


RCODE 



** TEST RETURN CODE 



RCODE 
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COMP 


99 
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LR 
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8 
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8 
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'VOLUME: ' 
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VOLM 


6 
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'RETURN CODE IS' 
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l 





RPGSCR: 



RPGCALL NAME=RPGSCR , CALL=SCRATCH , TYPE , FI LE , LIBR , VOLM , 
(RCODE, 4, F) 
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SEARCH 



FUNCTION 

Performs a binary search for a particular element in a specified table and indicates 
whether the element exists in the table. 



USAGE 

Pos 

argl 
arg2 
arg3 

arg4 

arg5 



(arg1,...,arg6) 
Argument Type 



Table 

Table Size 

Item 
Length 

Search 
Item 

Search 
Item Length 



Alpha 

Integer 

Integer 

Alpha 

Integer 



arg6 Ret. Code Integer 4 



Size Comments 

var Input table to be searched. 

4 Number of items in the input table. 

4 Length of each table item. 

Range is 1 to 256. 

var Value to be searched for in the table. 

4 Effective length to be used in searching for 

the supplied item in the table. Specifying a 
value less than the item length (arg3) allows 
the search to match fewer than the entire 
item length. If omitted, the item length 
(arg3) is assumed. 

If the search is successful, this is the index 
of the item found in the table. If unsuccess- 
ful, its value is 0. 



NOTES 



The table should be in either ascending or descending order. SEARCH might not 
correctly handle tables whose entries are not in ascending or descending order. 

If the table contains duplicate entries, the binary search might not find the first 
occurrence of the item in the table. 
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SEARCH Subroutine — A COBOL Example 



This program allows the user to search a five-item table of names to find the location of a specified 
name. 



000100 
000200 
000300 
000400 
000500 
00Q600 
000700 
000800 
000900 
001000 
001100 
001200 
001300 
001400 
001500 
001600 
001700 
001800 
001900 
002000 
002100 
002200 
002300 
002400 
002500 
002600 
002700 
002800 
002900 
003000 
003100 
003200 
003300 
003400 
003500 
003600 
003700 
003800 
003900 
004000 



'ADAMS" . 
'BROWN" . 
'CUNNINGHAM" 
'DESMOND". 
'EDWARDS" . 



IDENTIFICATION DIVISION. 
PROGRAM-ID. SEARCHC. 
ENVIRONMENT DIVISION. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
01 NAMES-LIST. 

03 FILLER PIC X(10) VALUE 

03 FILLER PIC X(10) VALUE 

03 FILLER PIC X(10) VALUE 

03 FILLER PIC X(10) VALUE 

03 FILLER PIC X(10) VALUE 
01 NAMES-TABLE REDEFINES NAMES-LIST. 

03 NAMES PIC X(10) OCCURS 5 TIMES. 
*AS EXPLAINED IN SECTION 2.2.2, COBOL ACCEPTS HALFWORD INTEGERS 
*0NLY. DEFINE A FOUR-BYTE GROUP ITEM TO BE COMPOSED OF TWO 
•HALFWORD-BINARY, ELEMENTARY ITEMS, AND USE THE LOW-ORDER TWO 
•BYTES FOR THE INTEGER. TO PASS AN INTEGER TO THE SUBROUTINE, 
"INITIALIZE THE HIGH-ORDER BYTES TO ZERO. 
01 TABLE-SIZE. 

03 FILLER USAGE IS BINARY VALUE ZERO. 

03 TABLE-COUNT USAGE IS BINARY VALUE 5. 

TABLE-ITEM-LENGTH. 

03 FILLER USAGE IS BINARY VALUE ZERO. 

03 TABLE-ENTRY-LENGTH USAGE IS BINARY VALUE 10. 

SEARCH-ITEM PIC X(10) . 

LOCATION. 

03 FILLER USAGE IS BINARY VALUE ZERO. 

03 INDEX-OF-ITEM USAGE IS BINARY. 
PROCEDURE DIVISION. 
START- PARAGRAPH. 

PERFORM MAIN-PARAGRAPH UNTIL SEARCH-ITEM = "Z". 

GO TO EXIT-PARAGRAPH. 
MAIN-PARAGRAPH. 

ACCEPT SEARCH-ITEM. 

IF SEARCH-ITEM = "Z" GO TO EXIT-PARAGRAPH. 

CALL "SEARCH" USING NAMES-TABLE, TABLE-SIZE, 
TABLE-ITEM-LENGTH, SEARCH-ITEM, LOCATION. 

DISPLAY INDEX-OF-ITEM. 
EXIT-PARAGRAPH. 

STOP RUN. 



01 



77 
01 
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SEARCH Subroutine - A FORTRAN Example 

This program allows the user to search a table of color names for an value that the user enters and 
indicates its position within the table. 

REAL*8 TABLE(13) , NAME 

INTEGER RCODE 

DATA TABLE/ 'BLACK' , 'BLUE' , 'BROWN' , 'GOLD' , 'GREEN' , 'GREY' , 
1 'ORANGE' , 'PURPLE' , 'RED' , 'SILVER' , 'TAN' , 'WHITE' , 'YELLOW'/ 
C ASK USER FOR A COLOR TO FIND 

WRITE(O.lOl) ' ENTER COLOR TO FIND (ENTER STOP TO QUIT)' 

READ (0,102) NAME 
C ENTERING STOP TERMINATES THE PROGRAM 

IF(NAME .EQ. 'STOP') GO TO 99 
C SET TABLE SIZE AND ELEMENT LENGTH 

ISIZE = 13 

LENGTH = 8 
C 
C CALL SEARCH SUBROUTINE 

CALL SEARCH (TABLE, ISIZE, LENGTH, NAME, RCODE) 
C 
C DISPLAY THE RETURN CODE ON THE WORKSTATION 

WRITE(0,103) RCODE 

101 FORMAT (A41) 

102 FORMAT (A8) 

103 FORMATdX, 'RETURN CODE = ',13) 
99 PAUSE 

END 
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SET 



FUNCTION 

Sets any of the allowable defaults that are available through the Command Processor 
SET Usage Constants function. 

USAGE (key1,rec1,...,keyn, recn) 

Arguments are specified in keyword-receiver pairs, where the keyword selects the 
default and the receiver specifies its new value. The user can specify any number of 
pairs, but each keyword must be immediately followed by a receiver. 

Each keyword is a 2-byte alpha value. The keywords, their associated receivers, and the 
defaults to be set are provided below. 



Recr Recr Receiver 

Keyword Type Size Value 

FC Alpha 1 Default file protection class. 

FN Integer 4 Default printer form number (0-255). 

IL Alpha 8 Default input library. 

IV Alpha 6 Default input volume. 

JC Alpha 1 Default job class for background processing. 

JL Integer 4 Default CPU time limit, in seconds, for background 

processing. 

JS Alpha 1 Default job status for background processing. 

Li Integer 4 Default lines per page for printer output. 

OL Alpha 8 Default output library. 

OV Alpha 6 Default output volume. 

PC Alpha 1 Default print class (A-Z). 

PL Alpha 8 Default program library (current). See Note. 

PM Alpha 1 Default print mode (S. H, K, or O). 

PR Integer 4 Default printer number for online printing. 

PV Alpha 6 Default program volume (current). See Note. 

RL Alpha 8 Run library (initial). See Note. 

RV Alpha 6 Run volume (initial). See Note. 

SV Alpha 6 Default spool volume. 

WV Alpha 6 Default work volume. 



SET-1 



NOTE 

"Current" refers to the library or volume that applies to the program containing the call 
to SET. "Initial" refers to the default library or volume which, when set, applies to the 
entire session. 
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SET Subroutine — A COBOL Example 

This program allows the user to set the default file protection class, lines-per-page for printer output, 
and print mode. The user enters the desired values via the ACCEPT statement. Since ACCEPT trans- 
fers alphanumeric data only, a BASIC subroutine using the CONVERT statement is called to convert 
the input for lines-per-page from alphanumeric to integer data. This is explained in Section 2.2.2. 

000100 IDENTIFICATION DIVISION. 

000200 PROGRAM-ID. SETC. 

000300 ENVIRONMENT DIVISION. 

000400 DATA DIVISION. 

000500 WORKING-STORAGE SECTION. 

000600 77 FILE-CODE PIC X(2) VALUE "FC". 

000700 77 FILE-CLASS PIC X. 

000800 77 LINES-CODE PIC X(2) VALUE "LI". 

000900*THE NEXT ITEM RECEIVES THE INPUT FOR LINES-PER-PAGE AND PASSES 

001000'IT TO THE BASIC SUBROUTINE. 

001100 01 LINES-VALUE. 

001200 03 SIGN-ITEM PIC X VALUE " + ". 

001300 03 LINES-NUM PIC X (8). 

001400*THE NEXT ITEM RECEIVES THE CONVERTED LINES-PER-PAGE AND PASSES 

001500 # IT TO THE SET SUBROUTINE. 

001600 01 LINES-PER PIC X(4). 

001700 77 PRINT-MODE-CODE PIC X(2) VALUE "PM". 

001800 77 PRINT-MODE PIC X. 

001900 PROCEDURE DIVISION. 

002000 MAIN-PARAGRAPH. 

002100 DISPLAY "TYPE IN FILE-CLASS, LINES-NUM, PRINT-MODE.". 

002200 ACCEPT FILE-CLASS, LINES-NUM, PRINT-MODE. 

002300*THE NEXT STATEMENT CALLS THE BASIC SUBROUTINE. SEE SECTION 

002400*2.2.2 FOR THE BASIC CODE. 

002500 CALL "9T04" USING LINES-VALUE, LINES-PER. 

002600 CALL "SET" USING FILE-CODE, FILE-CLASS, LINES-CODE, 

002700 LINES-PER, PRINT-MODE-CODE, PRINT-MODE. 

002800 DISPLAY "TO VERIFY RESULTS, USE PF KEY 2 FROM THE COMMAND PRO 

002900- "CESS0R.". 

003000 STOP RUN. 
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SET Subroutine — An RPG II Example 



This program allows the user to set default input and output libraries and volumes, as well as print 
class and print mode. The program displays a screen confirming that the parameters have been set 
as requested. 
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*** EXIT TO RPGCALL MACRO *** 
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1315 


'INPUT 
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'OUTPUT LIBRARY' 








1440 
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02200WSCR2 

02300W 0707 'PARAMETERS SET AS REQU' 

02400W 0729 'ESTED. PRESS ENTER TO' 

02500W 0751 ' END JOB.' 



RPGSET: 



RPGCALL NAME=RPGSET,CALL=SET,IL,LIBIN,IV,VOLIN,OL,OUTLB > 
OV.OUTVL, PC, CLASS, PM, MODE 
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SORT 



FUNCTION 

Sorts a character array on a specified field, in either ascending or descending order. 
Output from the subroutine can be either the sorted array or a locator-type array. A 
locator-type array contains pointers to the elements in the array and indicates the sorted 
order of those elements. 



USAGE (argl arg9) 

Pos Argument Type 



argl 
arg2 



Input 
Elements 



arg3 Element 
Length 

arg4 Output 



arg5 Start 

arg6 Sort 
Length 



Alpha 
Integer 



Size Comments 



var 
4 



Integer 4 

Alpha var 

Integer 4 

Integer 4 



arg7 Sort type Alpha 1 



arg8 Locator Alpha 1 

Flag 

arg9 Locator Integer 4 

Length 



Input array to be sorted. 

Number of elements in the input array. 
Range is to 32767. 

Length of each element in the array. Range is 
1 to 256. 

Output array to receive the sorted values or 
pointers (if locator type sort - see arg8). If 
omitted, the sorted elements are placed in 
the input array (argl). 

Starting position of the sort field in the ele- 
ment. Default is character 1 . 

Length of the sort field. 
Standard sort — a 255-byte sort field 
cannot be used with a 256-byte record. 
Locator-type sort — the sort length plus the 
locator size cannot exceed 256 bytes. 
Default is to sort the entire record. 

Type of sort to be performed: 
A = Ascending (default) 
D = Descending 

Flag for locator (addrout) type sort: 
S = Standard sort (default) 
L = Locator type sort 

Desired size of each locator element. Range 
is 1 to 4. Default is 2. 



NOTES 

1 . Arguments 4 through 9 are optional; however, if one is present, all previous argu- 
ments must be included. 

2. No check is made for appropriate locator element size (e.g., locator length of 1 
would be insufficient for an input array with more than 255 elements). 
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SORT Subroutine - A FORTRAN Example 

This program allows the user to perform a standard sort, in ascending order, on a table of 4-charac- 
ter values read from an external data file. Arguments 5 through 9 are omitted because the sort starts 
in column 1 and affects the entire record. 

C 'ARRAY1' CONTAINS THE UNSORTED TABLE 
C 'ARRAY2' CONTAINS THE SORTED TABLE 

DIMENSION ARRAYK12), ARRAY2U2) 
C READ TABLE OF 12 VALUES FROM DATA FILE 

DO 1 1=1,12 
1 READ(2,101) ARRAYKI) 
C 
C CALL SORT SUBROUTINE 

CALL S0RT(ARRAY1, 12, 4, ARRAY2) 
C 
C DISPLAY BOTH TABLES ON THE WORKSTATION 

WRITE (0,102) ARRAY1, ARRAY2 

101 FORMAT (A4) 

102 FORMATC UNSORTED: ' /3 (IX, 4 (IX, A4) /)/ ' SORTED:-' /3 (IX, 4 (IX, A4) / ) ) 
PAUSE 

END 
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STRING 



FUNCTION 

Performs the following string manipulation functions: 

1 . Moves a string to another variable and pads it with a user-specified character. 

2. Moves a portion of a string to another variable. 

3. Centers a string. 

4. Left- or right-justifies a string. 
Reverses the order of characters in a string. 



5. 
6. 



Translates the string according to a selected or user-specified translation 
table. 



USAGE (arg 1 , arguments) 

Arg1 defines the string function and determines the number and nature of the additional 
arguments. 



Move a string and pad it with a user-specified character 



Pos 

argl 
arg2 
arg3 

arg4 
arg5 

arg6 



Argument 

Function 

Input 

Input 
Length 

Output 

Output 
Length 

Pad 
Character 



Type 

Alpha 
Alpha 
Integer 



Size Comments 



2 

var 

4 



Alpha var 
Integer 4 

Alpha 1 



Value is MV 

String to be processed. 

Length of input string. 

Output location for the moved string. 

Length of output string. If omitted, assumed 
to be the input string length. Must be present 
if arg 6 is included. 

Character to be used as the pad if the output 

length (arg5) is greater than the input length 

(arg3). 

If omitted, blank (hex 20) is assumed. 

If included, arg 5 must also be present. 
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2. Move a contiguous string of characters from one location to another (move- 
indexed) 

Same as MV, but includes an offset for input and output locations (primarily for BASIC 
STR emulation). 



Pos Argument Type 



argl 
arg2 
arg3 

arg4 

arg5 
arg6 



Function 

Input 

Input 

Input 
Length 

Output 

Output 
Index 



arg7 Output 
Length 

arg8 Pad 



Alpha 
Alpha 

Integer 

Index 



Size Comments 



2 

var 

4 



Integer 4 



var 
4 



Alpha 
Integer 

Integer 



Alpha 1 

Character 



Value is Ml 

Input string to process. 

Offset (from 0) of the first character of the 
input string to be moved. 

Number of characters to be moved, starting 
with the character indicated by arg3. 

Output location for the moved string. 

Offset within the output string to move 
string to. Optional. If omitted, offset is 
assumed. 

Length of the output string. If omitted, length 
of the input string assumed. If present, the 
program must include arg6. 

Character to be used as the pad if the output 
length (arg7) exceeds the input length 
(arg4). If omitted, blank (hex 20) is assumed. 
If present, the program must include arg6 
and arg7. 



3. Center, left- or right-justify, or reverse the characters in the input string 
Pos Argument Type Size Comments 



argl 



Function 



Alpha 



arg2 Input 
arg3 Length 
arg4 Output 



Alpha var 
Integer 4 
Alpha var 



String manipulation function: 
CT = Center 
LJ = Left-justify 
RJ = Right-justify 
RV = Reverse 

Input string to process. 

Length of the input string. 

Output location for the shifted characters. 
Length is the same as that of the input 
string. Optional. If omitted, assumed to be 
the same as the input string (the string func- 
tion is performed "in place"). 
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4. Translate the input string with a user-supplied translation table 



Pos 


Argument 


Type 


Size 


Comments 


argl 


Function 


Alpha 


2 


Value is TT 


arg2 


Input 


Alpha 


var 


Input string to process. 


arg3 


Length 


Integer 


4 


Length of the input string 


arg4 


Translate 
Table 


Alpha 


256 


Table to be used for the tt 
character in the input strii 



arg5 Output 



Alpha 



var 



value is N is translated into the character in 
position (N+1) in the table. (See an ASCII 
Collating Sequence table for binary values of 
ASCII characters.) 

Input string translation. Optional. If omitted, 
the input string contains the translation. 



5. Translate the input string with a user-supplied translation list 



Pos 

argl 
arg2 
arg3 
arg4 



Argument 

Function 

Input 

Length 

Translate 
List 



Type 

Alpha 
Alpha 
Integer 
Alpha 



Size 

2 

var 
4 
var 



arg5 Output 



Alpha var 



Comments 



Value is TL 



Input string to process. 

Length of the input string. 

List of to/from character pairs used in the 
translation. Indicate the end of the list by the 
pair X'0000'. In each byte pair in the transla- 
tion list, all occurrences in the input string of 
the character indicated by the second byte 
are translated to the character indicated by 
the first byte. Any input characters not rep- 
resented in the list are not changed in the 
translation. 

Input string translation. Optional. If omitted, 
the input string contains the translation. 
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6. Translate ASCII input to EBCDIC or translate EBCDIC input to ASCII 



Pos Argument Type Size 

argl Function Alpha 2 

arg2 Input Alpha var 

arg3 Length Integer 4 

arg4 Output Alpha var 



Comments 

Translation function: 
AE = ASCII to EBCDIC 
EA = EBCDIC to ASCII 

Input string to translate. 

Length of the input string. 

Output location for translated characters. 
Length is the same as that of the input 
string. Optional. If omitted, the length is 
assumed to be the same as the input string 
(translation is performed "in place"). 



NOTES 



3. 



If the input and output locations are the same, the functions are performed "in 
place." 

With the exception of the MV and Ml functions, the results are not guaranteed to 
be correct if the input and output locations are different but overlap in some other 
way. 

The MV and Ml functions are always performed one byte at a time, from left to 
right. Thus, overlapping operands result in either "correct" moves or character 
propagation, depending on the type of overlap. This is similar to the way in which 
the BASIC "COPY" instruction operates. 
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STRING Subroutine — A FORTRAN Example 

This example demonstrates the center string (CT) and reverse string (RV) functions. Results are 
shown after the program. 

REAL'8 CHARS1, CHARS2 

CHARS1 = 'ABCD 

LENGTH = 8 
C 
C CALL STRING TO CENTER CHARS1 - RESULT IS CHARS2 

CALL STRING CCT', CHARS1, LENGTH, CHARS2) 
C 

WRITE(O.lOl) ' 12345678 12345678' 

WRITE(0,102) ' CT', CHARS1, CHARS2 
C 
C CALL STRING TO REVERSE CHARS1 - RESULT IS CHARS2 

CALL STRING CRV, CHARS1, LENGTH, CHARS2) 
C 

WRITE(0,102) ' RW , CHARS1, CHARS2 

101 FORMAT (A23) 

102 FORMAT (A3, 2(2X, A8)) 
PAUSE 

END 



The output from this program appears like this: 

12345678 12345678 

CT ABCD ABCD 

RV ABCD DCBA 
PAUSE: 
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STRING Subroutine — AN RPG II Example 



This program asks the user to input a 40-character string and choose a function (center, reverse, left 
justify, convert ASCII to EBCDIC, or move to a longer string and pad with a chosen character). The 
program performs the requested function and displays the results. The user can then make another 
choice. 

00100FDISPLAY DD F WS 



00110C 

0O12OC 

00200C 

0O3OOC 

00310C* 

00320C* 

00330C* 

00340C* 

00400C 

00403C* 

00404C* 

00406C* 

00410C 

00420C* 

00430C* 

00435C* 

00440C* 

00500C 

00600C 

00700C 

00800C 

00900C 

01000C 

01002C* 

01OO4C* 

01006C* 

01010C 

01020C 

01030C 

01040C 

01041C 

01050C 



TOP 



TAG 

SETOF 

ENBLEK1.K2.K3 

ENBLEK4.K5.KG 



88 



•** DISPLAY SCREEN ALLOWING USER TO CHOOSE STRING FUNCTION 
•*• OR TO END THE JOB *** 

ACCPTSCR1 

# ** END JOB IF PF 16 WAS PRESSED ,# * 

KG GOTO END 

*** PREPARE PARAMETERS TO PASS TO RPGCALL MACRO 
* # * (FOR ALL FUNCTIONS EXCEPT MOVE) * ## 



K5 
Kl 
K2 
K3 
K4 



Z-ADD40 


LEN 


40 


GOTO MOVE 






MOVE 'CT' 


FN 


2 


MOVE 'RV 


FN 


2 


MOVE 'LJ' 


FN 


2 


MOVE 'AE' 


FN 


2 



EXIT TO RPGCALL MACRO (FOR ALL FUNCTIONS EXCEPT MOVE) 



EXIT RPGST1 




RLABL 


FN 


RLABL 


STR 


RLABL 


LEN 


SETON 




GOTO ANSR 





88 
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01060C* 










01070C* 


* * H 


' PERFORM MOVE FUNCTION **" 




01080C* 










01100C 


MOVE 


TAG 






01200C 




move 'm 


'' FN 2 




01210C 




MOVE ' ' 


OSTR 70 




01220C 




Z-ADD70 


OLEN 40 




01300C 




EXIT RPGST2 




01610C 




RLABL 


OSTR 




01620C 




RLABL 


OLEN 




01630C 




RLABL 


PAD 




01640C* 










01650C* 


*" DISPLAY RESULT 


OF STRING MANIPULATION 


# * ♦ 


01660C* 










02110C 


ANSR 


TAG 






02120C 




ACCPTSCR2 




02130C 




GOTO TOP 




02140C 


END 


TAG 






02150C 




SETON 


LR 




02200WSCR1 










02300W 




0707 


'PLEASE ENTER A CHARACT ' 




02400W 




0729 


'ER STRING AND CHOOSE A' 




02500W 




0751 


' FUNCTION.' 




02660W 




1015 




STR 


02700W 




1210 


' PF 1 - CENTER' 




02800W 




1310 


'PF 2 - REVERSE" 




02900W 




1410 


'PF 3 - LEFT JUSTIFY' 




03000W 




1510 


'PF 4 - DISPLAY EBCDIC ' 




03010W 




1532 


'EQUIVALENT' 




03100W 




1610 


'PF 5 - MOVE TO A LARGE' 




03200W 




1632 


'R STRING AND PAD WITH ' 




03300W 




1654 


'A SPECIFIED CHARACTER' 




03340W 




1715 


' (PADDING CHARACTER = 


i 


03350W 




1736 




PAD 


03351W 




1737 


')' 




03355W 




2007 


'PRESS PF 16 TO END JOB 


i 


03400WSCR2 










03410W 


88 


0702STR 




STR 


03500W 


N88 


07020STR 




OSTR 


03600W 




1007 


'PRESS ENTER TO TRY AGA 


j 


03700W 




1029 


'IN.' 





40 



RPGST1: 



RPGST2 



RPGCALL NAME=RPGST1 , CALL=STRING , FN , STR , ( LEN , 4 , F) 



RPGCALL NAME=RPGST2 , CALL=STRING , FN , STR , ( LEN , 4 , F ) , OSTR , 
(OLEN, 4, F), PAD 
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SUBMIT 



FUNCTION 



Submits a background job to be run or held for later processing. 



USAGE (arg1 r ...,arg11) 

Pos Argument Type 

argl File Alpha 

arg2 Library Alpha 



Size Comments 



8 
8 



arg3 Volume Alpha 6 

arg4 Job Name Alpha 8 
arg5 Status Alpha 1 



arg6 Job Alpha 1 

Disposition 

arg7 Job Class Alpha 1 



arg8 



arg9 



Abort 
Action 



CPU Time 
Limit 



Alpha 



Integer 



Name of the procedure file to be submitted. 

Library containing the procedure. The 
default is the PROGLIB value, as defined by 
PF2 (SET) of the Command Processor. 

Volume containing the procedure. The 
default is the PROGVOL value, as defined by 
PF2 (SET) of the Command Processor. 

User-supplied name for the job using the 
submitted procedure. The default is blank. 

Status of the submitted job: 

R = Run immediately. 

H = Hold. 

Blank = Use the value specified by a SET 
SVC, a SET Procedure language state- 
ment, or by PF2 (SET) of the Command 
Processor. The default is blank. 

Disposition of the job after completion. 
D = Delete from queue (default). 
R = Return to queue. 

Job class of the procedure submitted. Must 
be a letter from A to Z or blank. If blank, use 
the value specified by the SET SVC, a SET 
Procedure language statement, or by PF2 
(SET) of the Command Processor. The 
default is blank. 

Action to take if the job aborts: 
D = Produce program dump. 
N = No program dump. 
R = Produce dump only if requested 
elsewhere in the program. (Default). 

CPU time limit, in 1/100 seconds: 
= No time limit (default). 
-1 = Use the value specified by a SET 
SVC, a SET Procedure language 
statement, or PF2 (SET) of the Com- 
mand Processor. 
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Pos Argument Type Size Comments 

arg10 Limit Alpha 1 Action to take if the CPU time limit (arg9) is 

Flag exceeded: 

C = Cancel program. 
P = Pause. 

W = Continue the procedure, but gener- 
ate an operator warning. (Default). 

arg 1 1 Ret. Code Integer 4 Error return code. See Table 3- 1 5 below. 

Arguments 2 through 1 are optional. If the program uses an argument, all the preceding 
arguments must be used. 



Table 3-15. SUBMIT Error Return Codes 



Return 

Code Meaning 

Successful. 

8 Volume not mounted. 

1 2 Volume used exclusively by another user. 

16 All buffers in use, unable to perform verification. 

20 File not found. 

24 Improper file type, or the file contains zero records. 

28 File access denied. 

32 VTOC error. FDX 1 and FDX2 do not agree. 

36 VTOC error. FDX2 and the FDR 1 and FDR2 do not agree. 

40 Invalid specification of file, library, and volume. 

48 System task not running, no spooled printing or interactive jobs. 

52 Error in performing XMIT to system task. 

56 Invalid options specified in argument list. 
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SUBMIT Subroutine — A BASIC Example 

This program allows the user to submit any procedure as a background job by specifying the Proce- 
dure language file, library, volume, and job names. The program provides default values for status, 
disposition, abort action, and limit action in lines 1 000-1 300. 

000100DIM FILES 08 

000200DIM LIBRARYS 08 

000300DIM VOLUMES 06 

000400DIM J0BNAMES 08 

000500DIM STATUSS 01 

000600DIM DISPOSITIONS 01 

000700DIM J0BCLASSS 01 

000800DIM AB0RTACTI0NS 01 

000900DIM LIMITACTIONS 01 

001000STATUSS ="R" 

001100DISPOSITIONS ="D" 

001200ABORTACTION$ ="R" 

001300LIMITACTION$ ="W" 

001400 

001500LO0P: 

001600GOSUB PUTSCREEN 

00170060SUB D0SUBMIT 

001800GOTO LOOP 

001900 

002000PUTSCREEN: 

002100ACCEPT 

002200 AT (01,10) , 

002300"Demonstration of Submitting a Background Job (SUBMIT) Subroutine 

002400 ", 

002500 AT (05,03), 

002600"Fill in the information requested below, press ENTER, to submit 

002700a job. ", 

002800 AT (07,03), 

002900 "FILE NAME:", 

003000 AT (07,17), FILES , CH(08), 

003100 AT (07,29), 

003200" (Procedure file to be submitted)", 

003300 AT (08,03) , 

003400 "LIBRARY: " , 

003500 AT (08,17), LIBRARYS , CH(08), 

003600 AT (09,03), 

003700 "VOLUME:" , 

003800 AT (09,17), VOLUMES , CH(06), 

003900 AT (10,03), 

004000 "JOB NAME: " , 

004100 AT (10,17), J0BNAMES , CH(08), 

004200 AT (10,29), 

004300"(Name of associated background job)", 
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004400 AT (11,03), 

004500"STATUS:", 

004600 AT (11,17), STATUS$ , CH(01), 

004700 AT (11,29), 

004800" (R-run;H-hold) " , 

004900 AT (12,03), 

005000"DISPOSITION:", 

005100 AT (12,17), DISPOSITIONS , CH(01), 

005200 AT (12,29), 

005300" (D-d equeue;R- requeue) " , 

005400 AT (13,03), 

005500"JOB CLASS: " , 

005600 AT (13,17), J0BCLASS$ , CH(01), 

005700 AT (14,03), 

005800 "ABORT ACTION: " , 

005900 AT (14,17), ABORTACTION$ , CH(01), 

006000 AT (14,29), 

006100" (D-program dump;N-no program dump;R-dump on request)" 

006200 AT (15,03) , 

0O6300"CPU LIMIT: " , 

006400 AT (15,17), CPULIMIT% , PIC(####), 

006500 AT (15,29), 

006600" (Time limit for CPU usage)", 

006700 AT (16,03), 

006800 "LIMIT ACTION: " , 

006900 AT (16,17), LIMITATIONS , CH(01), 

007000 AT (16,29), 

007100" (C-cancel program; P-pause ;W-warning message)", 

007200 AT (18,03), 

007300"RETURN CODE: " , 

007400 AT (18,17), RETURNCODE% , PIC(##) 

007500RETURN 

007600 

007700DOSUBMIT: 

007800 CALL "SUBMIT" ADDR(FILE$ , LIBRARY$, VOLUMES, 

007900 JOBNAMES , STATUSS , DISPOSITIONS , 

008000 JOBCLASS$,ABORTACTION$,CPULIMIT%, 

008100 LIMITACTIONS , RETURNCODE%) 

008200RETURN 
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U NITRES 

FUNCTION 

Allows the user to reserve or release a device or peripheral processor on the system. 

USAGE (argl arg3) 

Ft>s Argument Type Size Comments 

argl Function Alpha 2 Function code: 

D+ = Reserve the device 

D- = Release the device 

P+ = Reserve the peripheral processor 

P- = Release the peripheral processor 

arg2 Unit No. Integer 4 Number of the device or peripheral proces- 

sor. It must be nonnegative (only values 
0-255 are recognized; larger values produce 
an error return code). 

arg3 Ret. Code Integer 4 Error return code. See Table 3- 16 below. 

Table 3-16. UNITRES Error Return Codes 



Return 

Code Meaning 

Successful reserve/release. 

4 Invalid unit address in argument list. 

8 Invalid function code in argument list. 

1 2 Invalid unit type in argument list. 

1 6 (Reserved) 

20 PP specified for nonprogrammable device. 

24 PP reservation conflict. 

28 (Reserved) 

32 Release specified for a device or PP that the caller does not own. 

36 Invalid device type. 

40 Device reservation conflict. 
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UNITRES Subroutine — A COBOL Example 



This program allows the user to reserve and then release a device or peripheral processor interactive- 
ly by entering the unit number and type (D or P) at the workstation. Since the COBOL ACCEPT state- 
ment transfers only alphanumeric data, this program calls the BASIC subroutine 9T04, discussed in 
Section 2.2.2, to convert the entered unit number to a format that the UNITRES subroutine can use. 



000100 
000200 
000300 
000400 
000500 
000600 
000700 
000800 
000900 
001000 
001100 
001200 
001300 
001400 
001500 
001600 
001700 
001800 
001900 
002000 
002100 
002200 
002300 
002400 
002500 
002600 
002700 
002800 
002900 
003000 
003100 
003200 
003300 
003400 
003500 
003600 
003700 
003800 
003900 
004000 
004100 



IDENTIFICATION DIVISION. 
PROGRAM-ID. UNITRESC. 
ENVIRONMENT DIVISION. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
01 



X. 

X VALUE " + " . 
UNIT NUMBER TO 



FUNCTION. 

03 FUNCTION-NAME PIC 
03 FUNCTION-SIGN PIC 
*THE NEXT ITEM PASSES THE 
01 UNIT-NUMBER. 

03 SIGN-ITEM PIC X VALUE " + ". 
03 UNIT-VALUE PIC X(8). 
*THE NEXT ITEM RECEIVES THE CONVERTED 
"SUBROUTINE 

01 UNIT-INTEGER PIC X(4). 
*AS EXPLAINED IN SECTION 2.2.2, COBOL 
•ONLY. DEFINE A FOUR-BYTE GROUP ITEM 
•HALFWORD-BINARY ELEMENTARY ITEMS, AND 
•BYTES FOR THE INTEGER. 
01 RETURN-KODE. 

03 FILLER USAGE IS BINARY VALUE 
03 ERROR-CODE USAGE IS BINARY. 
PROCEDURE DIVISION. 
MAIN-PARAGRAPH. 

ACCEPT UNIT-VALUE. 
CALL "9T04" USING UNIT-NUMBER, 
ACCEPT FUNCTION-NAME. 
DISPLAY "PRESS ENTER TO RESERVE 
PERFORM CALL-PARAGRAPH. 
MOVE "-" TO FUNCTION-SIGN. 
DISPLAY "PRESS ENTER TO RELEASE 
PERFORM CALL-PARAGRAPH. 
GO TO EXIT-PARAGRAPH. 
CALL-PARAGRAPH. 

CALL "UNITRES" USING FUNCTION, 
IF ERROR-CODE NOT = DISPLAY 

GO TO EXIT-PARAGRAPH. 
DISPLAY "TO VERIFY RESULT USE PF 
" PROCESSOR.". 
EXIT-PARAGRAPH. 
STOP RUN. 



THE BASIC SUBROUTINE 



UNIT NUMBER FROM THE BASIC 



ACCEPTS HALFWORD INTEGERS 
TO BE COMPOSED OF TWO 
USE THE LOW-ORDER TWO 



ZERO. 



UNIT-INTEGER. 



UNIT "UNIT-VALUE. 



UNIT "UNIT-VALUE. 



UNIT-INTEGER, 
ERROR-CODE = ' 



RETURN-KODE. 
ERROR-CODE, 



KEY 6 FROM THE COMMAND 
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UPDATFDR 

FUNCTION 

Allows the user to change attributes of a file or library. The attributes are listed below. 

USAGE (argl arg5, arg6 [repeatable keyword-value pairs], .... arg8) 

Pos Argument Type Size Comments 



argl 


Update 
Range 


Alpha 


1 


Specifies range of the update: 
F = Update single file 
L = Update all files in a library 


arg2 


File Name 


Alpha 


8 


File to be modified. Ignored if argl =L 


arg3 


Library 


Alpha 


8 


Library. 


arg4 


Volume 


Alpha 


6 


Volume. 



The program can use the following two arguments as optionally repeatable keyword- 
value pairs. 



Pos Argument Type 



arg5 
arg6 



Pos 
arg7 



Keyword 
Value 

Keyword 

CD 

ED 

FC 

ID 

MD 

ME 

MR 

MW 

RS 

Argument 

Access 
Limit Flag 



Alpha 
Alpha 

Recr 
Type 

Alpha 
Alpha 
Alpha 
Alpha 
Alpha 
Alpha 
Alpha 
Alpha 



Type 

Alpha 



Size Comments 

2 File attribute to be changed, 
var New value. 

Recr Receiver 
Size Value 

6 Creation date in the form YYMMDD. 

6 Expiration date in the form YYMMDD. 

1 File protection class. 

3 Owner's ID. 

6 Last modification date in the form YYMMDD 

4 Special execute access flags. See Note 3. 
4 Special read access flags. See Note 3. 

4 Special write access flags. See Note 3. 

Value ignored. Release unused space in the 
filets). 

Size Comments 

1 Specifies access rights : 

L = Restricted to the user's access rights 
Blank or omitted -No restriction (use the 
special access rights of the program, if 
available) 
Optional. 
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Pos Argument Type Size 

arg8 Ret. Code Integer 4 



Comments 

Error return code. 

Nonzero value depends on the value of arg 1 : 
Arg1 = F: Return codes as follows: 
4-96= UPDATFDR return codes 
(see Table 3-17 below) 
1 04-1 96= Ret. Code for READFDR 

+ 100 
Arg1 =/.: Additional return codes: 
1 00= One or more files could 
not be updated (for any 
reason) 
204-296= Ret. Code for 

READVTOC + 200 



NOTES 

1 . Return codes are structured as described in the arg8 description for these reasons: 
for single-file updates, READFDR is called; for library updates, READFDR and 
READVTOC are both called. 

2. A "blocks-lost" condition, indicated by return code 44, is not detected if arg 1 =L. 

3. The ME, MR, and MW keywords require that the user have security administrator 
rights. The remaining keywords require only that the user be the creator of the file 
or files to be modified. 

4 For FORTRAN programs, the name of this subroutine must be specified as 
UPDFDR. 
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Table 3-1 7. UPDATFDR Error Return Codes 



Return 

Code Meaning 

File label updated. 

4 All buffers in use, no update. 

8 Volume not mounted, no update. 

1 2 Volume used exclusively by another user. 

1 6 Wrong disk type, no update. 

20 File not open in an exclusive mode for group 1 , group 2, and/or 

group 3, no update. 

24 Library not found. 

28 File not found. 

32 Update access to this file protection class denied, no update. 

36 File not closed for group 4 and/or group 5, no update. 

40 VTOC full, no spare for FDR2 label. 

44 VTOC full, no spare for freed extent. Extent lost. 

48 VTOC error, FDX1 and FDX2 do not agree. 

52 VTOC error, FDX2 and FDR do not agree. 

56 VTOC error, FDX1 and FDR do not agree. 

60 VTOC error, invalid data in FDR1 or FDR2. 

64 System/VTOC error, FLUB and FDR 1 do not agree. 
68 Disk I/O error, VTOC unreliable. 

72 Group 5 update attempted on nonprogram file. 
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UPDATFDR Subroutine — A COBOL Example 

This program allows the user to modify the expiration date, file protection class, and owner's ID for 
individual files or all the files in a library. 

000100 IDENTIFICATION DIVISION. 

000200 PROGRAM-ID. UPDTFDRC 

000300 ENVIRONMENT DIVISION. 

000400 DATA DIVISION. 

000500 WORKING-STORAGE SECTION. 

000600*THE FOLLOWING ITEMS ARE THE ARGUMENTS FOR THE UPDATFDR SUBROUTINE 

000700 77 UPDATE-RANGE PIC X(l). 

000800 77 FILE-NAME PIC X(8). 

000900 77 LIB-RARY PIC X(8). 

001000 77 V0L-UME PIC X(6). 

001100 77 EXPIRE-KEY PIC X(2) VALUE "ED". 

001200 77 EXPIRE-DATE PIC X(6). 

001300 77 PROTECT-KEY PIC X(2) VALUE "FC" 

001400 77 FILE-CLASS PIC X. 

001500 77 ID-KEY PIC X(2) VALUE "ID". 

001600 77 ID PIC X(3). 

001700 77 LIMIT-FLAG PIC X VALUE " ". 

001800*AS EXPLAINED IN SECTION 2.2.2, COBOL ACCEPTS HALFWORD INTEGERS 

001900'ONLY. DEFINE A FOUR-BYTE GROUP ITEM TO BE COMPOSED OF TWO 

002000'HALFWORD-BINARY, ELEMENTARY ITEMS, AND USE THE LOW-ORDER TWO 

002100*BYTES FOR THE INTEGER. TO PASS AN INTEGER TO THE SUBROUTINE 

002200'INITIALIZE THE HIGH-ORDER BYTES TO ZERO. 

002300 01 RETURNCODE. 

002400 03 FILLER USAGE BINARY VALUE ZERO. 

002500 03 ERROR-CODE USAGE BINARY. 

002600 PROCEDURE DIVISION. 

002700 MAIN-PARAGRAPH. 

002800 ACCEPT UPDATE-RANGE, FILE-NAME, LIB-RARY, VOL-UME 

002900 EXPIRE-DATE, FILE-CLASS, ID. 

003000 CALL "UPDATFDR" USING UPDATE-RANGE, FILE-NAME, LIB-RARY 

003100 VOL-UME, EXPIRE-KEY, EXPIRE-DATE, PROTECT-KEY 

003200 FILE-CLASS, ID-KEY, ID, RETURNCODE. 

003300 DISPLAY "TO VERIFY RESULTS USE PF KEY 5 FROM THE COMMAND PROC 

003400- "ESSOR.". 

003500 STOP RUN. 
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WSXIO 



FUNCTION 

Performs I/O operations at the workstation and returns values associated with those 
operations. 

This subroutine provides a variety of I/O operations. The following options are available 
in most, but not all, higher-level programming languages: 

Open or Close the Workstation file 

READ Altered 

READ Diagnostic 

READ Tabs 

WRITE Selected 

WRITE Tabs 

The VS Principles of Operation provides a description of these operations. 

USAGE (arg 1 , arg2, arguments) 

Arg1 defines the type of function to be performed, arg2 specifies a file or a User File 
Block (UFB). Arg 1 determines the number and nature of the remaining arguments. 

Pos Argument Type Size Comments 

argl Function Alpha 1 Type of function to be performed: 

= Open the workstation file 
C = Close the workstation file 
X = Perform an I/O operation 
W = Wait for interrupt 
A = Move AID character 

arg2 User File Alpha 140 File name (COBOL), file number (BASIC), 

Receiver parameter reference name for a UFB 

(Assembler), or data item used to hold a UFB 
address. A data item used to hold a UFB 
address must have a length of 1 40 and be 
fullword aligned before the file is opened. It 
can be examined or used at any time 
between OPEN and CLOSE, but it should not 
be changed during this time. 

The remaining arguments depend on the function type. If the function type is C, no fur- 
ther arguments are necessary. 
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1 . OPEN the Workstation file 
Pos Argument Type Size 

argl Function Alpha 1 



arg2 Device 



arg3 File Recr 



Integer 4 



Alpha 



140 



arg4 Ret. Code Integer 4 



NOTE 



Comments 

Value is 

Device number of workstation to be opened 
(must be nonnegative). If the device number 
is 255, the user's workstation is assumed. 

Area to be used as the UFB for the worksta- 
tion file. It is initialized to valid UFB informa- 
tion prior to OPEN. It can be an FD (COBOL), 
a file number (BASIC), a UFB block (Assem- 
bler), or a variable or array that this subrou- 
tine uses to hold the UFB. (If it is the latter, it 
must be fullword aligned.) It can be examined 
or used (standard DMS) at any time between 
OPEN and CLOSE, but should not be erased 
or otherwise radically changed during this 
time. 

Error return code for OPEN operation: 

= Successful. 

4 = Not a workstation. 

8 = OPEN error. The OPEN error status 
can be found in the UFB file status 
bytes FS1/FS2; either an Open Exit 
or a Cancel/Respecify exit was taken. 



Older versions of WSXIO did not require arguments 2 and 4. That argument list will con- 
tinue to be supported for a limited amount of time; programs using WSXIO with the 
previous argument list should be updated. 



Perform an I/O operation (the operations are listed in the description of argu- 
ment 3) 



Pos 


Argument 


Type 


Size 


Comments 


argl 


Function 


Alpha 


1 


Value is X 


arg2 


File Recr 


Alpha 


140 


As in OPEN. 
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Pes Argument Type Size 

arg3 Command Alpha 1 
Code 



arg4 Order 
Area 



Alpha var 



arg5 Order Integer 4 

Area Length 



arg6 Mapping Alpha var 

Area 



arg7 Mapping Integer 4 

Area Length 

arg8 lOSWRecr Alpha 8 



Comments 

Indicates the I/O operation to be performed. 
Arg3 is a hexadecimal character in the first 
byte of the I/O Command Word (IOCW). 
Any arg3 value is accepted; the following 
should be used to perf oem standard DMS 
functions: 

X'40' = READ 

X'44' = READ tabs 

X'48' = READ diagnostic 

X'50' = READ altered 

X'80' = WRITE 

X'84' = WRITE tabs 

X'90' = WRITE selected 

Order area to be transmitted to the worksta- 
tion for the I/O operation. Provided by the 
user program. 

Length of the order area. Value can be to 
Area 4096. The sum of arg5 and arg7 
cannot exceed 4096. Optional. Default is 4 
bytes. 

Mapping area transmitted to the workstation 
for the I/O operation, provided by the user 
program. 

Length of the mapping area. Value can be 
to Area 4096. 

Data item that receives the I/O Status Word 
(IOSW) after the I/O operation. 



NOTES 

1 . For READ and WRITE operations, arg4, arg6, and arg7 are mandatory. 

2. If possible, the order and mapping areas are sent to the workstation directly from 
the locations specified by arg4 and arg6; however, in the following situations, the 
data must be moved to a temporary location for the I/O operation. 

a) When the order and mapping areas do not occupy adjacent locations, and 
neither length is zero. 

b) When the combined area is not fullword aligned. 

c) When the combined area spans more than 2 contiguous pages of memory. 
The minimum amount of stack space required to properly align the data is 
used. 
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3. Wait for interrupt 
Pos Argument Type 

arg 1 Function Alpha 



arg2 
arg3 



File recr 

Timeout 
Value 



Alpha 
Integer 



Size 

1 

140 
4 



arg4 lOSWrecr Alpha 8 



Comments 

Value is W 

Indicates an instruction to wait for an unso- 
licited interrupt from the workstation. 

As in OPEN. 

Number of 1 /1 00 seconds to wait for an 
interrupt. 

Data item that receives the IOSW after the 
timeout is taken. If no interrupt occurs 
before the timeout is taken, the IOSW is 
unchanged. 



Return AID character 

their meanings.) 



(See Table 3- 1 8 below for a list of AID characters and 



Pes Argument Type Size Comments 



argl Function Alpha 

arg2 File recr Alpha 

arg3 AID recr Alpha 



1 Value is A 

Indicates that the AID character is to be 
moved to the data item referenced by arg3. 

140 As in OPEN. 

1 Data item that receives the current AID char- 

acter. This character is also available in the 
third byte of the IOSW immediately after the 
I/O operation. 
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Table 3-1 8. AID Characters and Their Meanings 



AID 


Hexadecimal 


ASCII 


Character 


Character 


Character 


Keyboard 






unlocked 






by write 


20 


(blank) 


Keyboard 






locked by 






write 


21 


/ 


ENTER key 


40 


@ 


PF1 


41 


A 


PF2 


42 


B 


PF3 


43 


C 


PF4 


44 


D 


PF5 


45 


E 


PF6 


46 


F 


PF7 


47 


G 


PF8 


48 


H 


PF9 


49 


I 


PF10 


4A 


J 


PF11 


4B 


K 


PF12 


4C 


L 


PF13 


4D 


M 


PF14 


4E 


N 


PF15 


4F 





PF16 


50 


P 


PF17 


61 


a 


PF18 


62 


b 


PF19 


63 


c 


PF20 


64 


d 


PF21 


65 


e 


PF22 


66 


f 


PF23 


67 


g 


PF24 


68 


h 


PF25 


69 


i 


PF26 


6A 


J 


PF27 


6B 


k 


PF28 


6C 


I 


PF29 


6D 


m 


PF30 


6E 


n 


PF31 


6F 


o 


PF32 


70 


P 
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WSXIO Subroutine — A COBOL Example 



This program opens the workstation file, performs a WRITE to the workstation, allows the user to 
modify fields already written, and performs a READ ALTERED (which reads into memory only the 
fields that have been altered). It also erases and protects the screen, performs a WRITE SELECTED 
(which writes to the screen only the fields that have been altered), and closes the workstation file. 
The program also displays the workstation's I/O Status Word (IOSW) after calling the subroutine 
HEXUNPK to convert the IOSW from ASCII characters to hexadecimal digits. 



000100 
000200 
000300 
000400 
000500 
000600 
000700 
000800 
000900 
001000 
001100 
001200 
001300 
001400 
001500 
001600 
001700 
001800 
001900 
002000 
002100 
002200 
002300 
002400 
002500 
002600 
002700 
002800 
002900 
003000 
003100 
003200 
003200 
003300 
003400 
003500 
003600 
003700 
003800 
003900 



USED FOR ARGUMENT 3 
THE SCREEN, AND FOR 



IDENTIFICATION DIVISION. 
PROGRAM-ID. WSXIOC. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
"THE FOLLOWING ITEMS WILL BE 
*C0DE) FOR THE ORDER AREA OF 
'CHARACTERS. 
FIGURATIVE-CONSTANTS. WRITE-COMMAND IS "80", 
FIRST-ORDER IS "01A0" 
SECOND-ORDER IS "0000" 
SELECT-COMMAND IS "90" , 
ALTERED-COMMAND IS "50", 
ERASE-PROTECT IS "0102" . 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT SCREEN, ASSIGN TO "SCREEN", "DISPLAY", 
ACCESS MODE IS RANDOM, 
PFKEY IS PFKEY-RECEIVE. 
DATA DIVISION. 
FILE SECTION. 
FD SCREEN, 

LABEL RECORDS ARE STANDARD. 
01 SCREEN-REC. 
03 ORDERAREA. 

05 ORDER-1 PICTURE IS XX. 
05 ORDER-2 PICTURE IS XX. 
03 SCREEN-AREA PIC X(1920). 
WORKING-STORAGE SECTION. 
01 MAPPING-AREA. 

03 FILLER PIC X(720) VALUE SPACE. 
*IN FAC-1 AND FAC-2, FIGURATIVE-CONSTANT "WRITE-COMMAND' 
*F0R THE BRIGHT-M0DIFY FIELD ATTRIBUTE CHARACTER. 
03 FAC-1 PIC X VALUE WRITE-COMMAND. 

VALUE "MODIFY THIS FIELD 
VALUE SPACE. 
WRITE-COMMAND. 
VALUE "DO NOT 
FLAG. IT 



(THE COMMAND 
FIELD ATTRIBUTE 



IS USED 



03 
03 
03 
03 



THE 
FOR 
77 



FIELD-1 PIC X(49) 
FILLER PIC XUOO) 
FAC-2 PIC X VALUE 
FIELD-2 PIC X(15) 
NEXT ITEM IS THE FUNCTION 
THE FIRST FUNCTION, OPEN. 
FUNC-FLAG PIC X VALUE "0' 



MODIFY" . 

IS INITIALIZED TO "0' 
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004000 
004100 
004200 
004300 
004400 
004500 
004600 
004700 
004800 
004900 
005000 
005100 
005200 
005300 
005400 
005500 
005600 
005700 
005800 
005900 
006000 
006100 
006200 
006300 
006400 
006500 
006600 
006700 
006800 
006900 
007000 
007100 
007200 
007300 
007400 
007500 
007600 
007700 
007800 
007900 
008000 
008100 
008200 
008300 
008400 
008500 
008600 
008700 
008800 
008900 



01 



77 



01 
01 



•THE NEXT ITEM IS THE COMMAND CODE INITIALIZED TO THE WRITE 
•COMMAND FOR THE FIRST USE OF THIS ARGUMENT. 

77 COMMAND PIC X VALUE WRITE-COMMAND. 
•AS EXPLAINED IN SECTION 2.2.2, COBOL ACCEPTS HALFWORD INTEGERS 
•ONLY. DEFINE A FOUR-BYTE GROUP ITEM TO BE COMPOSED OF TWO 
•HALFWORD-BINARY, ELEMENTARY ITEMS, AND USE THE LOW-ORDER TWO 
•BYTES FOR THE INTEGER. TO PASS AN INTEGER TO THE SUBROUTINE, 
•INITIALIZE THE HIGH-ORDER BYTES TO ZERO. 
01 ORDER-AREA-LENGTH. 

03 FILLER USAGE IS BINARY VALUE IS ZERO. 

03 ORDAREA-LENGTH BINARY VALUE IS +4. 

SCREEN-LENGTH. 

03 FILLER USAGE IS BINARY VALUE ZERO. 

03 ROW-LENGTH USAGE IS BINARY VALUE 1920. 

IOSW PIC X(8). 
•THE NEXT TWO ITEMS WILL BE USED BY HEXUNPK TO RETURN THE IOSW 
•IN HEX REPRESENTATION. 

CONVERTED-IOSW PIC X(16). 

EIGHT-BYTES. 

02 FILLER BINARY VALUE 0. 

02 FILLER BINARY VALUE +8. 
•THE NEXT ITEM IS USED FOR THE MAPPING AREA LENGTH ONLY DURING 
•THE OPERATION THAT ERASES AND PROTECTS THE SCREEN. 

01 MAP-LENGTH. 

03 FILLER USAGE IS BINARY VALUE 0. 
03 MAP-INTEGER USAGE BINARY VALUE 0. 

PROCEDURE DIVISION. 
OPEN-PARAGRAPH. 

CALL "WSXIO" USING FUNC-FLAG, SCREEN. 
DISPLAY "THE WORKSTATION FILE IS OPEN." 
WRITE-PARAGRAPH. 

MOVE MAPPING-AREA TO SCREEN-AREA. 
MOVE "X" TO FUNC-FLAG. 
•THE NEXT TWO STATEMENTS INITIALIZE THE WORKSTATION'S ORDER AREA. 
•FIRST-ORDER SETS THE ROW NUMBER TO ONE AND THE WRITE CONTROL 
•CHARACTER TO UNLOCK THE KEYBOARD AND SET THE CURSOR POSITION. 
•SECOND-ORDER INITIALIZES THE CURSOR COLUMN AND ROW ADDRESSES TO 
•ZERO. 

MOVE FIRST-ORDER TO ORDER-1. 
MOVE SECOND-ORDER TO ORDER-2. 
PERFORM CALL-WSXIO. 
READ-PARAGRAPH. 
•THE NEXT STATEMENT MOVES THE READ ALTERED COMMAND TO THE COMMAND 
•CODE ARGUMENT. 

MOVE ALTERED-COMMAND TO COMMAND. 
•THE NEXT STATEMENT WILL CAUSE THE CONTENTS OF SCREEN-AREA TO BE 
•DISPLAYED. THE READ WILL TAKE PLACE WHEN THE ENTER KEY IS 
•PRESSED. EITHER FIELD MAY BE MODIFIED. 

CALL "WSXIO" USING FUNC-FLAG, SCREEN, COMMAND, ORDERAREA, 
ORDER-AREA-LENGTH, SCREEN-AREA, SCREEN-LENGTH, IOSW. 
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009000*THE ALTERED FIELDS HAVE BEEN READ INTO MAIN MEMORY, BUT THE 

009-100'ENTIRE CONTENTS OF SCREEN-AREA REMAIN IN THE WORKSTATION'S 

009200'MEMORY. IN ORDER FOR TO DISPLAY ONLY THE MODIFIED FIELDS BY A 

009300 # WRITE SELECTED, THE CONTENTS OF SCREEN-AREA MUST BE REMOVED FROM 

009400*THE WORKSTATION'S MEMORY. THIS IS ACCOMPLISHED BY THE FOLLOWING 

009500*THREE STATEMENTS, WHICH ERASE AND PROTECT THE SCREEN. 

009600 MOVE WRITE-COMMAND TO COMMAND. 

009700 MOVE ERASE-PROTECT TO ORDER-1. 

009800 CALL "WSXIO" USING FUNC-FLAG, SCREEN, COMMAND, ORDERAREA, 

009900 SCREEN-AREA, MAP-LENGTH, IOSW. 

010000*NOW THAT THE WORKSTATION HAS BEEN CLEARED, ONLY THE MODIFIED 

010100'FIELDS WILL BE DISPLAYED WHEN THE NEXT STATEMENT IS EXECUTED. 

010200 PERFORM SELECT-PARAGRAPH. 

010300 CLOSE-PARAGRAPH. 

010400 MOVE "C" TO FUNC-FLAG. 

010500 CALL "WSXIO" USING FUNC-FLAG, SCREEN. 

010600 DISPLAY "THE WORKSTATION FILE IS CLOSED.". 

010700 STOP RUN. 

010800 CALL-WSXIO. 

010900 # THIS PARAPGRAPH CAUSES THE CONTENTS OF THE SCREEN-AREA TO BE 

OllOOO'WRITTEN TO THE SCREEN. SINCE THE WRITE COMMAND IS NOT FOLLOWED 

011100'BY A READ, THE CONTENTS ARE NOT HELD ON THE SCREEN. INSTEAD 

011200*THE IOSW IS DISPLAYED AFTER HEXUNPK IS CALLED. 

011300 CALL "WSXIO" USING FUNC-FLAG, SCREEN, COMMAND, ORDERAREA, 

011400 ORDER-AREA-LENGTH, SCREEN-AREA, SCREEN-LENGTH, IOSW. 

011500 CALL "HEXUNPK" USING IOSW CONVERTED-IOSW EIGHT-BYTES. 

011610 DISPLAY "IOSW = " CONVERTED-IOSW. 

011700 SELECT-PARAGRAPH. 

011800 DISPLAY "THE NEXT SCREEN WILL SHOW THE ALTERED FIELD ONLY." 

011900*IF THE USER DID NOT MODIFY EITHER OF THE FIELDS, ONLY THE CURSOR 

012000*WILL BE DISPLAYED ON THE SCREEN. 

012100 MOVE SELECT-COMMAND TO COMMAND. 

012200 MOVE FIRST-ORDER TO ORDER-1. 

012300 CALL "WSXIO" USING FUNC-FLAG, SCREEN, COMMAND, ORDERAREA, 

012400 ORDER-AREA-LENGTH, SCREEN-AREA, SCREEN-LENGTH, IOSW. 

012500*THE FOLLOWING TWO STATEMENTS CAUSE THE DISPLAY TO BE HELD ON THE 

012600*SCREEN UNTIL ENTER IS PRESSED. 

012700 MOVE ALTERED-COMMAND TO COMMAND. 

012800 CALL "WSXIO" USING FUNC-FLAG, SCREEN, COMMAND, ORDERAREA, 

012900 ORDER-AREA-LENGTH, SCREEN-AREA, SCREEN-LENGTH, IOSW. 
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